Skip to main content
Documentation & User Guides | Fotoware

Login Tokens (Legacy)

  1. Last updated
  2. Save as PDF
Applies to:FotoWare 8.0 Feature Release 2

 

Legacy Notice

This is a legacy integration feature. Do not use it for building new integrations.

  • Do you want your users to log in via an external service? Consider using SSO
  • Are you building an interactive app, such as a web, mobile, or desktop app? Consider using OAuth
  • Are you currently using the ArchiveAgent API? Consider using the new Fotoware API
  • Are you using legacy widgets? Consider using the new approach for embedding widgets using OAuth

The following content is legacy

Login tokens can be used to log on a user and create a user session from within a third-party application that handles authentication.

Note that this is not a method for authenticating API clients.

Usage

Login tokens are useful when creating a third-party application that integrates with the FotoWeb user interface. Normally, users have to log into FotoWeb using the FotoWeb login form to be authenticated in FotoWeb and to be able to access FotoWeb resources. With login tokens, a user only needs to log in once, using an authentication mechanism provided by a third-party application.

The login token is created by the third-party application and passed to FotoWeb in a URL. FotoWeb validates the login token and, if it is valid, redirects the user to any given resource inside FotoWeb.

Login tokens have limited lifetime, controlled by the third-party application generating them.

Note: Login tokens will not work for the site owner

Login tokens do not work for the user who is the site owner. This is for security reasons, to prevent impersonation of the site owner by a user who is not the site owner but does have permissions to manage users and security. Allowing impersonation of the site owner would be a security risk, as that user has special privileges.

Authentication

Before a third-party application generates a login token, it has to authenticate the user. This is entirely the responsibility of the third-party application and outside the scope of FotoWeb. For example, the third-party application may use its own username/password authentication and a mapping from its own users to FotoWeb users. It is also possible to use some form of single-sign-on,  LDAP (now deprecated and scheduled to be set to End of Life on January 1st, 2024), Active Directory authentication, or other methods.

Tip: FotoWeb can be integrated with your Active Directory. Learn how to do so and how to import the groups that should be allowed access to the system.

We do not recommend storing FotoWeb user passwords in third-party applications and there is no way to extract user passwords from FotoWeb. A third-party application using login tokens does not need to know FotoWeb user passwords.

Generating Login Tokens

Once the user has been authenticated, a third-party application can generate a token for logging the user in to FotoWeb. To generate the token, the application needs to implement the token generation algorithm and know the encryption secret of the FotoWeb site.

Every token consists of the: 

  • start and end date and time between which the token is valid
  • user name
  • signature

The signature is a hash value of the other values. It is used to prevent forgery of login tokens by malicious applications.

Sample code for generating tokens is publicly available:

  • C# (includes GUI tool)
  • PHP

Applying Login Tokens

To log in a user with a valid login token, redirect or link the user to the following URL in the browser:

http://hostname/fotoweb/services/tokenlogin?lt=token&to=url

where hostname is the host name of the FotoWeb site, token is the login token generated by the third-party application, and url is the URL to redirect the user to after successful login.

The to parameter is optional. If it is not given, the user is redirected to the start page of either the FotoWeb Pro interface or the main interface after successful login. This depends on whether or not the user has a Pro user license.

If the login token is valid, the user will be redirected to the given URL. Otherwise, an error page will be shown to the user. This should not normally happen since the third-party application should always create valid login tokens.

Token validity

Every token has a defined start and end time during which it is valid. Start and end times are given as UTC. When developing an integration that uses login tokens, you can decide the token validity.

A token is accepted by the server if and only if the UTC time on the server is within the validity range at the time of receiving the token.

Even if the client and server clocks are in sync (as they often are in a domain with SNTP time syncing), latency can cause additional differences between the time the token is created and the time it is received. Clock differences in both directions can cause the token to be received after, and even before, it is valid.

 

To avoid such problems related to token validity, we recommend the following:

  • Ensure the host that creates the tokens and the FotoWeb server have synchronized clocks, ideally set to the correct time. The clocks don't need to be highly accurately synced. A few seconds in either direction should not cause any issues.
  • When creating a token, define the validity range such that it begins slightly before the time the token is created and ends slightly after the time the token is expected to be received, taking the expected latency into account.
Note

You SHOULD NOT set the start time (S) to the creation time (C) because this does not allow for clock differences where the host's clock that creates the token is behind the clock of the FotoWeb server. However, if the clocks are in sync, latency usually mitigates this problem, which means that the minimum latency becomes the maximum acceptable time difference.