Jwt Token Authentication

Introduction

The API supports JWT token authentication from version 11.15.0 onwards.

The standard workflow is

sign in by providing credential to obtain tokens
use access token in Authorization header while invoking API end points
use refresh token to get a new access token when previous is expired
sign out when refresh token is no longer needed

Previously, only Basic Authentication was supported by the API. It is possible to keep this type of authentication, concurrently with token authentication or not.

Tokens

The API uses JWT tokens of limited life time to manage access to end points. There are two types of tokens: the long-lasting refreshment token and the short-lived access token.

refreshment token

The refreshment token is mainly used to obtain access tokens. It can also be stored by the client to implement a "Remember me" feature.

The sign in end point creates a refreshment token and the sign out end point destroy it. Alternatively, a token may expire after its maximum lifetime has been reached, whether it is revoked by an administration operation or has reached a maximum age if this option is enabled.

access token

An access token is used as authorization to invoke an end point. It cannot be revoked and becomes invalid when it expires or reaches its maximum age if this option is activated. An access token can also become invalid on demand by the server.

token invalidity

When a token is invalid, the authentication and authorizations associated with it are refused by the API services. A token may be invalid because it has expired, because it has been revoked (or invalidated) or because it is not recognized by the server as valid.

JWT tokens

The REST API uses JWT tokens (JSON Web Tokens). A JWT token is a three Base64-URL (UTF-8) strings separated by dots. The three parts are:

header
Header consists of two parts: the type of the token, which is always JWT, and the hashing algorithm begin used to build the signature part of the token. These two informations are stored in a JSon object which is encoded to form the first part of the token.
The hash algorithms supported by the REST API are:
- HS256 (HMAC SHA256)
- HS384 (HMAC SHA384)
- HS512 (HMAC SHA512)
Default is HS256, but you can changed it in plug-in configuration.
Payload
The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional data. The claims are also stored in a JSon object which is encoded.
1. Registered claim names
  - iat
  - iss
  - sub
  - exp
  - nbf (optional)
  - jti (only for refreshment tokens)
2. Public claim names (OpenID)
  - name (optional)
  - email (optional)
Signature
The signature is used to verify the message wasn’t changed along the way. The secret used to sign the token is not public and can change at any time. It is possible to configure the generation of this secret in the plug-in configuration. Signature is also encoded.

Message Authentication Code (MAC)

The tokens created by the API are not intended to be used for any purpose other than API access authentication (or token refreshment with this API). If the customer wants to use the token to exploit his information, outside the authentication system, he can use a specific end point to validate the token, then use a standard JWT API to extract the data from the payload. The MAC is private (only known by the server), so it is not possible for the client to modify the user data.. The server can reset the MAC, making the token invalid.

Invokation of services

Authorization Bearer

To invoke an API service with token authentication, simply pass the token through the Authorization header, specifying the Bearer type.

Example:

GET https://application/api/rest/dam/data/asset/55
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1Mzc0NTY3NjMsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTA4MC9lbmdpbmVwa2ciLCJ3dHlwIjoiVSIsInN1YiI6ImpvZWwuZHJpZ28iLCJuYW1lIjoiSm_Dq2wgRHJpZ28iLCJlbWFpbCI6ImpvZWwuZHJpZ29Ad2VkaWEuZnIiLCJ1c2lkIjoiMTIiLCJleHAiOjE1Mzc0OTk5NjN9.sy-ZmujVMU4P1xeQ6_qBf-fjUSHdH1MDbe-S0LpoSMI

Example js/jquery/ajax

var assetId = $("#assetid-field").val(); // get assetId input field

if ( assetId=="" || assetId==null || assetId===undefined ) {
	return;
}

 var opts = {
    url: 'https://<app>/api/rest/dam/data/asset/' + assetId,
	beforeSend: function(request) {
	    // pass access token as Bearer
        request.setRequestHeader("Authorization", "Bearer " + accessToken);
	},
	method: 'GET', // since jQuery 1.9
	type: 'GET', // prior jQuery 1.9
	done: function(data){ // replace success with done prior jQuery 3.0
	    if ( data["status"]== 200 ) {

		    // success

		    // show asset id
		    $("#assetid-display").text(assetId);

		    // show asset data
		    $("#assetdata").html( jsonToHtml(data.response.data) );

		    // replace img src with signature in for thumbnail
		    $("#assetimage").prop("src", 'https://<app>/api/rest/dam/data/asset/' + assetId + '/binary?variation=thumbnailSmall&atk=' + signToken );

    	} else {

		    // failure

    	    // $("#errorMessage").text("GET ASSET KO / " + data["status"] + " / " + data["message"] );

    	}
	},
	fail: function(xhr, status, error) { // replace fail with error prior jQuery 3.0
		// failure

        // $("#errorMessage").text("GET ASSET KO / " + error );
    }
};

$.ajax(opts);

Query parameter / Signature token

DEPRECATED

To allow the invocation of the token binary recovery service by placing a URL in the src attribute of an img HTML tag, it is possible to use a request parameter for this end point. To do this, use the signature token as the value of the atk parameter.

Example:

GET https://application/api/rest/dam/data/asset/55/binary?variation=thumbnailSmall&atk=ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBZWFFpT2pFMU16YzBOVFkzTmpNc0ltbHpjeUk2SW1oMGRIQTZMeTlzYjJOaGJHaHZjM1E2T1RBNE1DOWxibWRwYm1Wd2EyY2lMQ0ozZEhsd0lqb2lWU0lzSW5OMVlpSTZJbXB2Wld3dVpISnBaMjhpTENKdVlXMWxJam9pU21fRHEyd2dSSEpwWjI4aUxDSmxiV0ZwYkNJNkltcHZaV3d1WkhKcFoyOUFkMlZrYVdFdVpuSWlMQ0oxYzJsa0lqb2lNVElpTENKbGVIQWlPakUxTXpjME9UazVOak45LnN5LVptdWpWTVU0UDF4ZVE2X3FCZi1malVTSGRIMU1EYmUtUzBMcG9TTUk

Authenticate end point (Create tokens)

URL: https://<app>/api/rest/signin
Method: POST

Parameters

The parameters can be passed through the content type application/x-www-form-urlencoded or multipart/form-data.

login: the user login
password: the password
application: application name (optional)
userid: application user (optional, taken into account only for the connection by application)
exp: desired expiration time pour the refreshment token (optional)
- a date, as UTC Unix epoch time
- an ISO datetime (yyyy-MM-dd’T’HH:mm:ss or yyyyMMdd’T’HHmmss)
- unlimited, for an unlimited time token (The expiration date can never exceed the limits set elsewhere).
- other value or parameter omitted means default value depending on the context
sessionauth (deprecated): (optional, boolean, false by default) set the session mode on (invoking API with session) (this option must be allowed by API server configuration, see allowSessionAuth (default is true), or can be set automatically to true by default by API server configuration, see sessionAuth (default is false))
cookieauth: (optional, boolean, false by default) set the cookie mode on (invoking API with JWT cookie) (this option must be allowed by API server configuration, see allowJWTCookieAuth (default is true))

Response

The response is application/json, status 201 (created), containing mainly :

refreshToken: refreshment JWT Token
accessToken: access JWT Token
signature: query authentication parameter for binary end point

Example:

additional informations for OAuth2 sign in

Depending of the OAuth2 server configuration, you can get additional informations about the user account:

state: the OAuth2 state returned while the OAuth2 processus
loginHints: An object with the id of the OAuth2 authentication server and the login hint you can send in parameter loginHint of the OAuth2 login end point
idToken: the openid token
could contains user informations as login hints by example

Example:

Problem with ajax about multipart/form-data (missing boundary in content type header)

There is a problem with content type multipart/form-data using a HTML form and an ajax request. You can bypass it this way (jquery):

With fetch, do not set Content-Type header to multipart/form-data explicitely :

Basic Authentication

It is possible to invoke this end point using Basic authentication. The use is exactly the same as for invoking any other end point in Basic authentication.

Refresh token end point (Create new access token)

URL: https://<app>/api/rest/token
Method: GET, POST

Parameters

token: the refresh token

Response

The response is exactly the same as for the end point signin.

Authentication

This end point can be invoked without authentication, but you can pass the access or refresh token to Bearer in the Authorization header. In this case, it will be checked and compared to the token passed as a parameter and you may get a 401 Unauthorized error in response if the tokens do not conform. However, the expiration of the access token is never verified in order to be able to obtain a new access token after its expiration.

Sign out end point (Delete/Revoke refresh token)

URL: https://<app>/api/rest/signout
Method: DELETE

Parameters

token: the refresh token

Authentication

This end point can be invoked without authentication, but you can pass the access or refresh token to Bearer in the Authorization header. In this case, it will be checked and compared to the token passed as a parameter and you may get a 401 Unauthorized error in response if the tokens do not conform. However, the expiration of the access token is never verified in order to be able to revoke a token even after its expiration.

Validate end point (Validate token)

URL: https://<app>/api/rest/validateToken
Method: GET, POST

Parameters

token: the token to be validated

Responses

HTTP Code	Definition

HTTP Code	Definition
200	Token is valid
401	Token is invalid

Authentication

This end point can be invoked without authentication, but you can pass the access or refresh token to Bearer in the Authorization header. In this case, it will be checked and compared to the token passed as a parameter and you may get a 401 Unauthorized error in response if the tokens do not conform. However, the expiration of the access token is never verified in order to be able to obtain a new access token after its expiration.

Special case of the cookie mode

This mode is dedicated to an application environment within a browser.

Invocations

The response is different (does not contain the tokens)

Life time management

Transfer from an application token to a user token

Configuration

Configuring the plug-in

sessionAuth: boolean (default is false), enable session cookie authentication, only out of production mode (because of possible exploitation by CSRF attack)
tokenHash: (optional) base for MAC hash key
tokenCleaningPeriod: The trigger period for the process of deleting expired tokens, in seconds (1800 seconds by default, i.e. 30 minutes). Use 0 to disable the process.
tokenLongLifeTime: the duration of a long life token, in seconds (default is 86400 seconds, i.e. 24 hours)
tokenShortLifeTime: the duration of a short life token, in seconds (default is 1200 seconds, i.e. 20 minutes)
tokenMaxAge: (optional) if specified, the maximum lifetime of a token, regardless of long and short life time
jwtAlgorithm: JWT token MAC algorithm
- HS256: HMAC-SHA256 algorithm (default)
- HS384: HMAC-SHA384 algorithm
- HS512: HMAC-SHA512 algorithm