OAuth JWT Bearer Authentication

Available to Private Apps only. Used when there is no third party involved for service calls or on behalf of the user/account who created the App.

This is a more secure process to that of the Client Credentials process and requires an OAuth 2 Server Key. Your application calls the Evance API on behalf of your account rather than on behalf of a user. 

Overview

To support JWT Bearer Authentication, first create an OAuth 2 Server Key within your API control panel. 

Then, your application prepares to make authorised API calls by using the Server Key credentials to request an access token from the OAuth 2 authentication server. 

Finally, your application may use the access token to call Evance APIs.

Creating a Server Key

After adding a Private App to your API console you will need to do the following:

  • Create an OAuth 2.0 Server Key. When prompted give the key a title. The title is used for your reference only and may be any meaningful name. 
  • Download the Private Key JSON file which will contain your Server Key Credentials. The fille will look something like this:
{
    "account": "example.evance.me",
    "client_id": "2b4ec2959c42e02089abbf8069c53956.2.app.evance.me",
    "private_key": "d92b988985628fdd9ebdd71607d7890a01185671bb98e89f39421b88cf93c33c",
    "algorithm": "HS256"
}


Creating the JWT Bearer

A JWT is composed of three dot separated parts: a header, a claim set, and a signature. The header and claim set are JSON objects serialized to UTF-8 bytes, then encoded using the Base64url encoding.

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

The JWT header

The header consists of two fields: the signing algorithm (defined in your credentials) and the format of the assertion.

{"alg":"HS256","typ":"JWT"}

The Base64url representation of this looks like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9


The JWT claim set

The JWT claim set includes the permissions being requested (scopes), the target of the token, the issuer, the time the token was issued, and the lifetime of the token. Most of the fields are mandatory. Like the JWT header, the JWT claim set is a JSON object and is used in the calculation of the signature.

The required properties of the claim set are as follows:

iss The client_id from your server key credentials.
scope A space-delimited list of the permissions that the application requests.
aud The intended target of the assertion. When making an access token request this should be set to:
https://{account}/oauth/token where {account} is replaced by your account URL.
exp The expiration time of the assertion, specified as seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum of 1 hour after the issued time.
iat The time the assertion was issued, specified as seconds since 00:00:00 UTC, January 1, 1970.


An example of the JSON representation of these properties:

{
    "iss": "2b4ec2959c42e02089abbf8069c53956.2.app.evance.me",
    "scope": "account.readonly",
    "aud": "https://example.evance.me/oauth/token",
    "exp": 1487843714,
    "iat": 1487840114
}

The JSON claim set should then be serialized to a UTF-8 and Base64url-safe encoded string. For example:

ewogICAgImlzcyI6ICIyYjRlYzI5NTljNDJlMDIwODlhYmJmODA2OWM1Mzk1Ni4yLmFwcC5ldmFuY2UubWUiLAogICAgInNjb3BlIjogImFjY291bnQucmVhZG9ubHkiLAogICAgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuZXZhbmNlLm1lL29hdXRoL3Rva2VuIiwKICAgICJleHAiOiAxNDg3ODQzNzE0LAogICAgImlhdCI6IDE0ODc4NDAxMTQKfQ

The JWT signature

The JWT is calculated using the correct signing algorithm defined in the alg property of the JWT header. The input for the signature is as follows:

{Base64url encoded header}.{Base64url encoded claim set}

For example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ewogICAgImlzcyI6ICIyYjRlYzI5NTljNDJlMDIwODlhYmJmODA2OWM1Mzk1Ni4yLmFwcC5ldmFuY2UubWUiLAogICAgInNjb3BlIjogImFjY291bnQucmVhZG9ubHkiLAogICAgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuZXZhbmNlLm1lL29hdXRoL3Rva2VuIiwKICAgICJleHAiOiAxNDg3ODQzNzE0LAogICAgImlhdCI6IDE0ODc4NDAxMTQKfQ

Please check the correct encoding algorithm to use below:

HS256 SHA256 HMAC encoding using the private_key provided in your credentials file. 
RS256 SHA256 using RSA private key provided in your credentials file. 


Note: Evance currently defaults credentials for signing with HS256 only. 

The signature must then be Base64url encoded. The header, claim set, and signature are concatenated together with a period (.) character. The result is a JWT ready for transmission. 


Making the access token request

Having generated the signed JWT, your application can use it to request an access token. The access token request is an HTTPS POST request, and the body is URL encoded. The URL is as defined in the aud property of your claim set (e.g. https://example.evance.me/oauth/token).

The following parameters are required in the HTTPS POST request:

grant_type urn:ietf:params:oauth:grant-type:jwt-bearer
assertion The JWT, including signature.


A successful request will receive a JSON response from the server similar to the following:

{
    "access_token": "43e213757dd5a224ace6ffc22b8c436219c5830b",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}

You now have an access_token with a 1 hour lifespan, with which to make further requests to the Evance API. When your access_token expires you will need to repeat this process to gain further API access.

COVID-19 NOTICE – Business as Usual
Evance continues to provide all services and support throughout this difficult period. See our full statement here .