This is a legacy integration feature. It should not be used for building new integrations.
- Do you want your users to log in via an external service? Please consider using SSO
- Are you building an interactive app, such as a web app, mobile app or desktop app? Please consider using OAuth
- Are you currently using the ArchiveAgent API? Please consider using the new FotoWare API
- Are you using legacy widgets? Please consider using the new approach for embedding widgets using OAuth
ARTICLE CONTENT BELOW IS LEGACY
Login tokens can be used to log on a user and create a user session from within a third-party application which handles authentication.
Note that this is not a method for authenticating API clients.
Login tokens are useful when creating a third-party application which integrates with the FotoWeb user interface. Normally, users have to log into FotoWeb using the FotoWeb login form in order 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, which is controlled by the third-party application generating them.
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 or 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
- Start and end date and time between which the token is valid
- User name
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:
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:
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.
to parameter is optional. If it is not given, then 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.
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 in the integration.
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 at which the token is created and the time at which 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:
- Make sure that the host that creates the tokens and the FotoWeb server have synchronized clocks, ideally set to the correct time. It is not necessary for the clocks to be highly accurately synced. A few seconds in wither direction should not be a cause of issues.
- When creating a token, define the validity range such that is begins slightly before the time at which the token is created and ends slightly after the time at which the token is expected to be received, taking the expected latency into account.
You SHOULD NOT set the start time (S) to the creation time (C), because this does not allow for clock differences where the clock of the host that creates the token is behind the clock of the FotoWeb server. However, if the clocks are in sync, this problem is usually mitigated by latency, which means that the minimum latency becomes the maximum acceptable time difference.