Skip to main content


Documentation & User Guides | FotoWare

User Authentication for Embeddable Widgets


FotoWeb can provide some of its functionality to third-party applications through embeddable widgets, such as the Selection widget and the CMS export widget.

In order to use these widgets, a user first has to be authenticated in FotoWeb to get access to FotoWeb resources such as archives and albums. There are two methods of authenticating a user in an embeddable widget:

This article describes the advantages and disadvantages of each approach and how to integrate an embeddable widget into a third-party application such that the preferred authentication method is used.

Interactive Authentication

If this authentication mode is used, the user will see a login form before being able to use the selection widget. After entering a valid username and password, the user will be taken to the actual widget.

The login form stores a permanent cookie in the browser, so the same user will not be asked to log in again from the same browser unless cookies are deleted.

When using Interactive Login, users are prompted to authenticate with username and password. These are then stored in a cookie.

Advantages of Interactive Authentication

  • Very easy to integrate.
  • The third-party application does not need to know any FotoWeb usernames.
  • The third-party application does not need to be trusted, because it does not store any FotoWeb credentials.

Disadvantages of Interactive Authentication

  • Users have to log in to multiple applications (FotoWeb and the third-party application).
  • Users have to remember multiple usernames and passwords.

How to use Interactive Authentication

Simply embed the widget in the application using an IFRAME or other methods. When the user visits the URl of the widget, e.g., /fotoweb/widgets/selection, then FotoWeb will automatically show a login form if necessary. There is nothing for the integrator to do.

Single Sign On (SSO) for Widgets

If this authentication mode is used, then the user will be authenticated in FotoWeb automatically without having to type a username and password. Users log in only to the third-party application (or only to Windows or some other system, if the third-party application itself supports some kind of SSO).

The third-party application is responsible for authenticating users and mapping them to FotoWeb users.

The FotoWeb username has to be known for each user. Then the third-party application creates a widget login token and passes it to the FotoWeb widget.

Advantages of SSO

  • Users only need to log in once.
  • Users do not need to know their FotoWeb credentials.

Disadvantages of SSO

  • The integration is more complex and requires extra programming work.
  • The third-party application must map its own users to FotoWeb users and store FotoWeb usernames.
  • The third-party application must be fully trusted by the FotoWeb server, because it can log in any user.
  • The integration must include a server component for generating the login tokens.

How to use SSO

The third-party application must authenticate each of its own users to determine that the current user is authorized to use the FotoWeb widget as a given FotoWeb user. Note that for licensing reasons, it is necessary that different users (logging in from different browsers) have distinct user accounts in FotoWeb. You can not have one shared account for using a widget.

Once the user is authenticated, the third-party application generates a widget login token (as described below). The lifetime of the token should not be more than a few seconds or minutes, giving enough time for the user's browser to open the widget URL and for the server to process the request.

The login token is then passed to the widget URL as in the following example for the selection widget:


where FOTOWEB_HOSTNAME is the hostname of the FotoWeb site, and LOGIN_TOKEN is the widget login token created by the third-party application.

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.

Warning: Never put the encryption secret into JavaScript or HTML code or anything visible to users. Login tokens must be generated in a server component.

Every token consists of

  • 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 in a GIT repository.



Logging in to a widget creates a persistent token for the user. There is a limited number of these tokens. If the same user logs in too many times (e.g., due to the user switching machines or many users sharing the same machine), the user may run out of tokens, and the system administrator may have to reset tokens for that user as described here. This is to prevent license violation such as many users sharing the same user account.

If SSO is used, and the user already has a persistent token, then the login token is ignored, and no new persistent token is created. This means that the same user can log in an unlimited number of times on the same browser using SSO without running out of persistent tokens. Logging in interactively, however, always creates a new persistent token. Third-party applications do not need to care about whether a user already has a persistent token or not (nor are they able to find out). This is handled automatically by FotoWeb and the user's browser.

  • Was this article helpful?