Skip to main content
Documentation & User Guides | FotoWare

Authorization of single-page JavaScript web apps (SPA) without back end

  1. Last updated
  2. Save as PDF

Single-Page JavaScript Web Apps without Back-end

This variant of the authorization process is for single-page web applications containing only static JavaScript code that is purely executed in the browser, i.e., there is no back-end / server code (PHP, ASP.NET, Python or Node.js), and it is not considered feasible to add a back-end component. A single-page web app is a public client, because it cannot securely store a secret, as the secret would be exposed to the user and the user agent in plain text JavaScript code. This means that single-page web apps apps cannot authenticate themselves to FotoWeb. Single-page web apps use implicit code grant, which means that the client receives an access token directly in response to the authorization request, rather than an intermediate authorization code.

The access token will be exposed to the user and to the user agent.

Implicit grant is considered less secure than authorization code grant, and it is highly recommended to add a back-end component to a web application and use the process for regular web applications instead. Implicit grant is easier to implement and should only be used if adding a back-end component is not possible or not feasible, for example when developing a JavaScript-only plug-in for an existing native or web application.

Refresh tokens are not supported with this approach, so the user will always be authorized to use the app only for a short time. FotoWeb will ask the user for consent every time the app is authorized again. This may be inconvenient to the user and may be avoided by adding a back-end component and using the approach for regular web applications instead.

Configuring CORS

Unless the application and FotoWeb are hosted on the same domain, you will need to enable Cross Origin Request Sending (CORS). The configuration of CORS is outlined in a separate topic.

User Experience

The user experience is the same as for a regular web application.

Application registration

When registering the application in the FotoWeb site settings (Settings tab, then Services > Applications), choose Native / mobile.
No client secret is generated.

Application_registration_-_without_back_end.png

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.

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=token&
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    state=STATE

where

Parameter

Description
response_type REQUIRED. Must always be token.
client_id REQUIRED. The unique ID of the client, which was obtained during client registration.
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.
state

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

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 registered for the client and, if given, the redirection URI passed in the request as redirect_uri.

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

https://myapplication.com/oauth2/callback#
    access_token=ACCESS_TOKEN&
    token_type=bearer&
    expires_in=EXPIRES_IN_SECONDS
    state=STATE

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.
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 application can obtain the access token by parsing the fragment part of the redirection URL.

The server will not issue a refresh token if implicit grant is used. When the access token has expired, the only way to obtain a new access token is to repeat authorization.

Implementation in JavaScript

The following JavaScript functions can be used to implement OAuth 2.0 in a single-page application:

function createState()
{
    var text = "";
    var possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_~.";
    for (var i = 0; i < 16; ++i)
        text += possible.charAt(Math.floor(Math.random() * possible.length));


    return text;
}


function requestAuthorization(tenantURL, clientID, redirectURI)
{
    var state = createState();
    sessionStorage.setItem('state', state);


    window.location = tenantURL + "/fotoweb/oauth2/authorize?" +
        "response_type=token&" +
        "client_id=" + clientID + "&" +
        "redirect_uri=" + encodeURIComponent(redirectURI) + "&" +
        "state=" + encodeURIComponent(state);
}


function getAccessToken()
{
    var state = sessionStorage.getItem('state');
    if (state === null) return null;


    var params = window.location.hash.substring(1).split('&');
    var token = null;
    var stateValid = false;
    for (var i = 0; i < params.length; ++i)
    {
        var pair = params[i].split('=');
        if (decodeURIComponent(pair[0]) === 'access_token')
        {
            token = decodeURIComponent(pair[1]);
        }
        else if (decodeURIComponent(pair[0]) === 'state') {
            if (state === decodeURIComponent(pair[1]))
                stateValid = true;
            else
                alert("Invalid state! Someone is trying to mess with you!")
        }
    }


    if (stateValid)
        return token;


    return null;
}

The requestAuthorization function redirects the user to the authorization endpoint of FotoWeb. It may be called, for example, when the user clicks a "Log in with FotoWeb" button. The parameters are as follows:

The getAccessToken function reads the access token from the fragment part of the URL after authorization was successful.

This implementation validates the OAuth 2.0 state parameter by creating a random value before the authorization process and passing it to the getAccessToken function using session storage.

This prevents cross-site request forgery (CSRF) and embedding the app into other apps (mash-ups) by ensuring that the app only accepts access tokens it has itself requested.

Any additional parameters to the application may be passed through the authorization process in session storage.