Skip to main content
Documentation & User Guides | Fotoware

Web Application or API authorization

Web application or API

This variant of the authorization process is for web applications or web APIs (from now on called web apps) containing code executed on the server side, such as PHP, ASP.NET, Python, or Node.js. A web app is a confidential client because it can securely store a secret on the server side without exposing it to users and user agents (browsers). Web apps use authorization code grants, meaning the client first receives an intermediate authorization code from the server, which is then used to request an access token for accessing the FotoWeb API. This two-step process requires the client to send a second request to the server, where the client authenticates itself using the client secret. This provides additional security and protection against malicious clients attempting to gain access tokens.

User experience

  1. The user navigates to the client application in the browser
  2. If the user isn't logged into FotoWeb in the browser, then the standard FotoWeb login page is shown. Otherwise, proceed to step 3.
  3. The user may be asked to authorize the application to access the user's information. This is done in a user interface that is part of FotoWeb, which displays the application's name, a logo, and a list of permissions to be granted to the application.
  4. The user is redirected to the application and signed in. The application can now use the FotoWeb API to access information in FotoWeb and carry out actions on the user's behalf.

Application registration

  1. From the Tools menu (cogwheel icon), go to Site Configuration > Integrations > Applications. The Applications view opens. 

OAuth_Web_application_-_API_settings.png

  1. Select Add application (or Edit to edit an existing application).
  2. Select a type from the Type drop-down list.
  • If you select Native/mobile - enter a name in the Name field. In the Client ID field, you can enter an an existing client ID or leave this field empty to generate a new client ID. Select Add to add redirect URIs.
  • If you select Web App/ API - enter a name in the Name field and select Add to add redirect URIs.
  • If you select Non-interactive/script - enter a name in the Name field.
  1. Select Save. The client secret is displayed in the dialog that opens. 
    Note: Make a note of the client secret (or store it immediately in application code or configuration), as there is no way to recover it after application registration. If the client secret is lost, you must generate a new one in the application registration interface.
  2. Select OK to close the dialog. The newly registered application is now listed in the Applications view. 

User consent

A custom text can be added to the user consent dialog in Markdown format. It is also possible to include a URI to a privacy policy web page that governs the use of the system.

This information will be displayed in the consent dialog when the application requests access to the site so the user can review it before proceeding.

Disabling user consent

Integrations that use a client secret allow the possibility to turn off the user consent dialog altogether. This is recommended only for trusted enterprise integrations, where the application and the Fotoware tenant are owned by the same organization.

Protocol flow

The client opens a browser window to the following URL (line-breaks are added for readability. All parameter values must be URL-encoded):

https://myfotowebserver.com/fotoweb/oauth2/authorize?
    response_type=code&
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    state=STATE&
    code_challenge=CODE_CHALLENGE&
    code_challenge_method=S256

 where

Parameter Description
client_id REQUIRED. The unique ID of the client, which was obtained during client registration.
code_challenge REQUIRED: PKCE code challenge. See PKCE Reference.
code_challenge_method REQUIRED: PKCE code challenge method. See PKCE Reference.
redirect_uri

The redirection endpoint URI of the client.

If given, it MUST match with one of the redirection endpoint URIs registered for the client.

OPTIONAL if the application only has one registration endpoint.

REQUIRED if the application has more than one registration endpoint.

response_type REQUIRED. Must always be code.
state

REQUIRED: This SHOULD be a unique, cryptographically safe random string.

OAuth clients are REQUIRED to use the PKCE parameters code_challenge and code_challenge_method for additional security. However, for legacy reasons, these parameters are OPTIONAL for web applications.We strongly recommend using PKCE, as recommended by the OAuth standard.

For more information on generating the value for code_challenge, see the section "Proof Key for Code Exchange"

This request may result in the user being shown a login prompt for FotoWeb.

On success, the server responds by redirecting the user to the redirection endpoint URI of the client. This is always one of the redirection endpoint URIs registered for the client and, if given, the redirection URI passed in the request as redirect_uri.

Parameters are added to the query part of the redirection URI as follows (line-breaks added for readability. All parameter values are URL-encoded):

https://myapplication.com/oauth2/callback?
    code=AUTHORIZATION_CODE&
    state=STATE

where

 

Parameter Description
code The authorization code which is used to request the access token in the next request
state

This is always identical to the string passed to the request in the state parameter.

The client SHOULD check that the returned string is identical to the sent string.

This is to protect against cross-site request forgery (CSRF).

The client then makes the following request to the token endpoint to obtain the access token (line-breaks are added for readability.

This request MUST NOT be sent by the user agent (browser), as it would expose client credentials and access tokens to the user agent, resource owner and potentially others. For example, if the client is a web application, then this request SHOULD be sent by the back-end (server) of the application, rather than JavaScript code running in the browser (which would also fail due to cross-site request limitations (CORS)).

If the client is a web application without a back-end (pure AJAX application with a static web server), or sending the request from the back-end is not feasible, then please use the authorization process for single-page JavaScript web apps without back-end instead.

All parameter values MUST be URL-encoded.

POST https://myfotowebserver.com/fotoweb/oauth2/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json
 
grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER

where

Parameter Description
grant_type REQUIRED. Must always be authorization_code.
client_id REQUIRED. The unique ID of the client, which was obtained during client registration.
client_secret

REQUIRED. The secret of the client, which was obtained during client registration.

code REQUIRED. The authorization code which was returned by the authorization request.
redirect_uri

The redirection endpoint URI of the client.

REQUIRED if the redirection_uri parameter was also given in the authorization request, and its value must be identical.

MUST NOT BE GIVEN if the redirection_uri parameter was not given in the authorization request.

code_verifier REQUIRED: PKCE code verifier. See PKCE Reference.

On success, the server responds as follows:

200 OK
Content-Type: application/json

with the following response body:

{
  "access_token": ACCESS_TOKEN,
  "token_type": "bearer",
  "expires_in": EXPIRES_IN_SECONDS,
  "refresh_token": REFRESH_TOKEN
}

where

Parameter Description
access_token The access token that is used to authorize requests to the FotoWeb API 
token_type This is always bearer.
expires_in Number of seconds after which the token is expected to expire.
refresh_token OPTIONAL: A refresh token that can be used to request a new access token. For more information, see the section "Refreshing Tokens".

The application can obtain the access token by parsing the response body.

Refresh tokens are highly sensitive, as they have long (or infinite) expiration times and can be used to request new access tokens.

A client SHOULD store the refresh token in a safe place so it cannot be accessed by unauthorized parties. A client SHOULD NOT expose a refresh token to a user agent (browser). A client that does not use refresh tokens SHOULD NOT store the refresh token at all.