Page Comparison

...

The API supports JWT token authentication from version

The standard workflow is

1. sign in by providing credential to obtain tokens

2. use access token in Authorization header while invoking API end points

3. use refresh token to get a new access token when previous is expired

4. 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.

...

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:

1. 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.

2. 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)

3. 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)

...

Query parameter / Signature token

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.

...

• 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

Response

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

• refreshToken: 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

...

• 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: the openid token

• could contains user informations as login hints by example

Example:

{
  tokenType: "Bearer",
  refreshToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1Mzc0NjM2NDQsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTA4MC9lbmdpbmVwa2ciLCJ3dHlwIjoiUiIsInN1YiI6ImpvZWwuZHJpZ28iLCJuYW1lIjoiSm_Dq2wgRHJpZ28iLCJlbWFpbCI6ImpvZWwuZHJpZ29Ad2VkaWEuZnIiLCJ1c2lkIjoiMTIiLCJleHAiOjE1Mzc1NTAwNDQsImp0aSI6Ijg2MSJ9.Fvc1UJu0kjfFaydIA0-t3cKjZ7rMY6s5htUxi-0lcmk",
  accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1Mzc0NjM2NDQsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTA4MC9lbmdpbmVwa2ciLCJ3dHlwIjoiVSIsInN1YiI6ImpvZWwuZHJpZ28iLCJuYW1lIjoiSm_Dq2wgRHJpZ28iLCJlbWFpbCI6ImpvZWwuZHJpZ29Ad2VkaWEuZnIiLCJ1c2lkIjoiMTIiLCJleHAiOjE1Mzc1MDY4NDR9.GqDb_CR8zVja2xW6LNk3QA6bff78BGGUjz_ArHwTXVE",
  signature: "ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBZWFFpT2pFMU16YzBOak0yTkRRc0ltbHpjeUk2SW1oMGRIQTZMeTlzYjJOaGJHaHZjM1E2T1RBNE1DOWxibWRwYm1Wd2EyY2lMQ0ozZEhsd0lqb2lWU0lzSW5OMVlpSTZJbXB2Wld3dVpISnBaMjhpTENKdVlXMWxJam9pU21fRHEyd2dSSEpwWjI4aUxDSmxiV0ZwYkNJNkltcHZaV3d1WkhKcFoyOUFkMlZrYVdFdVpuSWlMQ0oxYzJsa0lqb2lNVElpTENKbGVIQWlPakUxTXpjMU1EWTRORFI5LkdxRGJfQ1I4elZqYTJ4VzZMTmszUUE2YmZmNzhCR0dVanpfQXJId1RYVkU",
  links: {
    href: "https://application/api/rest/signin",
    refreshTokenHref: "https://application/api/rest/token?token=ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBZWFFpT2pFMU16YzBOak0yTkRRc0ltbHpjeUk2SW1oMGRIQTZMeTlzYjJOaGJHaHZjM1E2T1RBNE1DOWxibWRwYm1Wd2EyY2lMQ0ozZEhsd0lqb2lVaUlzSW5OMVlpSTZJbXB2Wld3dVpISnBaMjhpTENKdVlXMWxJam9pU21fRHEyd2dSSEpwWjI4aUxDSmxiV0ZwYkNJNkltcHZaV3d1WkhKcFoyOUFkMlZrYVdFdVpuSWlMQ0oxYzJsa0lqb2lNVElpTENKbGVIQWlPakUxTXpjMU5UQXdORFFzSW1wMGFTSTZJamcyTVNKOS5GdmMxVUp1MGtqZkZheWRJQTAtdDNjS2paN3JNWTZzNWh0VXhpLTBsY21r",
    signoutHref: "https://application/api/rest/signout?token=ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBZWFFpT2pFMU16YzBOak0yTkRRc0ltbHpjeUk2SW1oMGRIQTZMeTlzYjJOaGJHaHZjM1E2T1RBNE1DOWxibWRwYm1Wd2EyY2lMQ0ozZEhsd0lqb2lVaUlzSW5OMVlpSTZJbXB2Wld3dVpISnBaMjhpTENKdVlXMWxJam9pU21fRHEyd2dSSEpwWjI4aUxDSmxiV0ZwYkNJNkltcHZaV3d1WkhKcFoyOUFkMlZrYVdFdVpuSWlMQ0oxYzJsa0lqb2lNVElpTENKbGVIQWlPakUxTXpjMU5UQXdORFFzSW1wMGFTSTZJamcyTVNKOS5GdmMxVUp1MGtqZkZheWRJQTAtdDNjS2paN3JNWTZzNWh0VXhpLTBsY21r"
  },
  state: "h2o2",
  loginHints: {
    id: "google",
    loginHint: "joel.drigo@wedia.fr"
  },
    idToken: {
    iss: "https://accounts.google.com",
    azp: "[...].apps.googleusercontent.com",
    aud: "[...].apps.googleusercontent.com",
    sub: "10105[...]4799",
    hd: "wedia.fr",
    email: "joel.drigo@wedia.fr",
    email_verified: true,
    at_hash: "5D2TEN[...]aTRHb4Q",
    name: "Joël DRIGO",
    picture: "https://lh4.googleusercontent.com/-JvH[...]s96-c/photo.jpg",
    given_name: "Joël",
    family_name: "DRIGO",
    locale: "fr",
    iat: 1543424259,
    exp: 1543427859
    },
 version: "1.0",
 status: 201,
 time: 617
}

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

...

• URL: https://<app>/api/rest/token

• Method: GET, POST

Parameters

• token: the refresh token

...

• URL: https://<app>/api/rest/validateToken

• Method: getGET, POST

Parameters

• token: the token to be validated

Responses

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