Widget Integrations (Legacy)

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Legacy Notice

Note: Legacy Widget and API Key Authentication are deprecated and will be set to End of Life on January 1st, 2025.

If you have implemented custom integrations with FotoWeb, such as CMS integrations, we recommend updating the authentication methods in use to OAuth, which was introduced in FotoWeb FR12 (version 8.0.850).

Legacy authentication methods, including FWAPIToken, have been deprecated and will be removed in the future.

Starting with FotoWeb feature release 12 (build 8.0.850), integrations using the FotoWeb widgets should use OAuth 2.0.
This is described in Using embeddable widgets.

The methods described in this article exist for backward compatibility only and will be completely discontinued in the future.

Existing integrations written for older FotoWeb versions will continue to work, provided the "Enable Legacy Widget Integrations" option is enabled in the site settings (under Applications). For sites that do not use any integrations of this kind, we recommend leaving this option disabled.

We recommend updating existing integrations to use the new method.

The legacy methods of authorizing widgets to access FotoWeb have the following minor security risks:

The selection widget may be embedded by arbitrary web sites, including malicious sites. Although there is no way for a malicious site to obtain an access token in this way, the malicious site may get access to data about selected assets.
The legacy method of interactive authentication involves opening the FotoWeb login page in an IFRAME, thus making legitimate apps using the FotoWeb widgets harder to distinguish from phishing sites that are impersonating the FotoWeb login page to steal passwords or attempting to gain authorization via clickjacking attacks.
The export widget, when used in the legacy way, is vulnerable to cross-site request forgery (CSRF). While nothing harmful can be done using this attack, it is always better to prevent cross-site attacks altogether.
Using login tokens requires the encryption secret of a tenant to be stored in the back-end component of an application. This is highly sensitive information that allows the holder to authorize themself to access FotoWeb as any user. The encryption secret MUST only be given to trusted applications and stored securely, e.g., on the server side only, NOT in client-side JavaScript, or anywhere it could be exposed to the user or user agent.

Note that these security risks are present in older and newer versions of FotoWeb. The use of OAuth 2.0 in newer versions neither increases nor mitigates these risks.

The legacy methods described here are only supported for the selection widget and the export widget, not for any other (including future) widgets.

Interactive authorization

If this authentication mode is used, the user will see the FotoWeb 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.

To use this method, embed the widget with no URL parameters:

<iframe src="https://acme.fotoware.cloud/fotoweb/widgets/selection"></iframe>

Starting with FotoWeb 8.0 Feature Release 12, users can log in using SSO (e.g., Azure AD, Windows Active Directory, SAML) in applications using this method. With previous versions of FotoWeb, only username and password authentication are supported.

This authorization method will also set a temporary cookie, which allows the user agent to use the export widget so the export widget can be embedded with no additional authorization parameters:

<iframe src="https://acme.fotoware.cloud/fotoweb/widgets/publish?i=ASSET_URL"></iframe>

Login tokens

Login tokens are another legacy authorization method that allows a third-party application to authorize a widget without asking the user to enter any credentials. This assumes that the application has already authenticated the user in an unspecified way (e.g., using the FotoWeb API, Active Directory, or its own user database with a mapping to FotoWeb users).

NOTE: 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:


<iframe src="https://acme.fotoware.cloud/fotoweb/widgets/selection?lt=LOGIN_TOKEN"></iframe>

The export widget is embedded in the same way as when using interactive authorization:

<iframe src="https://acme.fotoware.cloud/fotoweb/widgets/publish?i=ASSET_URL"></iframe>

Generating Login Tokens

To generate a login token, the application needs to implement the token generation algorithm and know the encryption secret of the FotoWeb site.

IMPORTANT: Never put the encryption secret into JavaScript, 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 (external link).