User authentication with the Archive Agent API
An Archive Agent client must authenticate itself as a FotoWeb user in order to access archives in FotoWeb. There are several ways to accomplish this.
Method 1: Passing Credentials in the Query String
This authentication method is stateless and does not require storing any persistent information on the client side. However, user credentials have to be sent with every request, which requires that the client application always knows the user's password.
The following query string can be added to every request to Archive Agent for authentication:
Note that the credentials are sent in plain text. It is therefore highly recommended to use an encrypted connection (HTTPS).
Method 2: One-Time Authentication with Credentials
This authentication method requires the use of the user's credentials (username and password) only once. An initial request generates a device token, which can be stored by the client application and sent with every subsequent request to Archive Agent.
The device token is requested as follows:
POST /fotoweb/cmdrequest/Login.fwx Content-Type: application/x-www-form-urlencoded u=USERNAME&p=PASSWORD
Note that the user credentials (the last line) are embedded in the body of the request. However, they are still being sent in plain text. It is therefore highly recommended to use an encrypted connection (HTTPS).
The server responds to the request as follows:
200 OK Set-Cookie: FWSession=token
where token is the device token. It can be sent with every request to Archive Agent to authenticate as the given user by adding the following request header:
Every client application should request one device token per distinct user that is accessing the Archive Agent API and store it persistently (for example, in a file on disk or in a database). A new device token for the same user should be requested only if a request to Archive Agent fails due to an invalid device token.
Device tokens can be revoked for each user by the system administrator.
- Many HTTP clients automatically handle cookies. When using such a HTTP client in a client application, it is not necessary to manually parse the
Set-Cookieheader and set the
Cookieheader on each request. However, when reading the device token from persistent storage, it needs to be added to the cookie list of the HTTP client.
- Each user can have more than one device token, but there is an upper limit. Device tokens are also used by FotoWeb Desktop and the mobile FotoWeb applications on iOS and Android. If too many device tokens are created for the same user, they have to be revoked by the administrator to allow new device tokens to be created. Therefore, client applications should always reuse device tokens for as long a they are valid and store them on disk or in a database.
- Despite the name,
FWSessionis not a session cookie. No session will be listed in the session list in the FotoWeb configuration interface. There is no such thing as a logout request. Device tokens remain valid forever until they are revoked by the administrator.
The name of the cookie,
FWSession, is for legacy reasons only. Creating a device token does not create a user session. Consequently, no entry appears in the session list in Operations Center. This behavior is different from FotoWeb 7.0, where the above request created a user session, and
FWSessionwas used as a session cookie. The name "device token" is due to the fact that device tokens are also used by the FotoWeb mobile applications.
Method 3: One-Time Authentication with Login Tokens
This authentication method is similar to the previous one, except a login token is used to initially authenticate the user, rather than the user name and password. This avoids the necessity of giving the user's password to the API client.
At first, the API client must create a login token based on the user name and the global encryption secret of the server. This is described in detail in the article about Login Tokens.
The login token must then be passed to the first request as a query string parameter, as follows:
If authentication with the login token succeeds, then the server sends a device token in the response:
For more information about device tokens, see the description of the previous method, in particular the remarks section.
It is OK (but not recommended) to send a (new) login token with every request. If the client already has a device token, and the device token is sent to the server as an
FWSession cookie, then the login token is ignored, and the existing device token is used.
This approach does not send any plain text passwords to the server. However, the token can still be stolen and used for authentication within its lifetime. Also, the token does contain the user name in plain text (encoded as base64). Therefore, using a secure connection (HTTPS) is highly recommended.
Which Authentication Method should be used?
For most scenarios, the third method using login tokens and device tokens is the preferred one, since it does not require giving user passwords to an integration. However, the integration does need the encryption secret of the server and is therefore able to authenticate all users whose user names are known to it. Therefore, the integration has to be fully trusted by the FotoWeb administrator and all users of the FotoWeb system.
The second method can be used if users should be prompted for their password before being allowed to use an application which uses the Archive Agent API. Then the password entered by the user can be used to authentication. Note that, also with this method, the integration has to be fully trusted by all FotoWeb users and by the FotoWeb administrator, because it can see plain-text user passwords and (in theory) store them.
The first method has the advantage of being simple and stateless. If an integration only makes one request at a time, then it is as good as the second method.
None of these methods are suitable if the integration cannot be fully trusted by the FotoWeb administrator or FotoWeb users.
Validity of Image IDs
Some ArchiveAgent methods return image IDs. These IDs may be linked to a certain client (distinguished by its device token, i.e., the value of its
FWSession cookie). Within the same client, these IDs are valid permanently. However, device tokens can be revoked by administrators, which also makes all linked image IDs invalid. Furthermore, different clients cannot exchange image IDs.
To avoid problems, it is best to see image IDs as temporary, and they should only be passed from one request to the next few requests sent by the same client. Image IDs should not be stored in databases or any other persistent storage.