OpenID Connect

Evance's OAuth 2.0 APIs can be used for both authentication and authorisation. 

This document describes our OAuth 2.0 implementation for authentication, based on the OpenID Connect specification. 

OpenID Connect extends the OAuth 2.0 Authorization Code Process allowing you to use your Evance website as an identity platform, or single sign-on (SSO) system, based on the authentication performed by Evance's OAuth 2.0 Authorization server. 

In this document we explain how you can integrate a client, such as a website, with your Evance website as a single sign-on (SSO) solution. This is ideal if you have an external website, such as a forum, you would like users to log in to using credentials they have on your Evance website. 

Obtain OAuth 2.0 Web Client credentials

Before you can begin you will need OAuth 2.0 Web Client credentials, which you can obtain from your admin console. To do this, follow the instructions appropriate for your Private App or Public App.

Set a redirect URI

When creating your credentials you must provide a valid redirect URI. The redirect URI determines where Evance sends responses to your authentication request. Your redirect URI must be HTTPS with a valid certificate. 

Authenticating a user

Authenticating a user is done by obtaining an ID token and validating it. ID tokens are a standardised feature of the OpenID Connect specification designed for use in sharing identity information.

Follow these steps to authenticate a user:

  1. Create an anti-forgery state token
  2. Send an authentication request to your Evance website
  3. Confirm the anti-forgery state token
  4. Exchange the authorisation code for an access token and ID token
  5. Obtain user information from the ID token
  6. Authenticate the user


1. Create an anti-forgery state token

You can help prevent user from request forgery attacks by creating a unique session or CSRF token that holds state between your app and the user's client. Matching the token after the user completes the OAuth log in process verifies the user made the request and not a malicious attacker.

2. Send an authentication request to your Evance website

You will need to redirect your user over an HTTPS GET request to the following URI:

https://{domain}/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={nonce}&scope={scopes}&state={state}

{domain} The live/preferred domain for your website.
{client_id}  Replace with your App's Client ID from your OAuth 2.0 Web Client credentials. 
{redirect_uri} Replace with the URI you wish to redirect the user to after they have authorised the App. This must be identical to the redirect URI stored in your App's settings. 
{nonce} A random unique unguessable string/number generated by your App for the authorization request. Evance will return this key to your redirect_uri for your App to check.
{scopes} A space separated list of Scopes. You must include the openid as a scope to obtain an idtoken
{state} The value of the anti-forgery unique session token generated in step 1.

 

3. Confirm the anti-forgery state token

The response is sent to the redirect_uri specified in the authentication request. All responses are returned in the string with the following parameters.

state The value of the anti-forgery unique session token generated in step 1.
code A one-time authorization code, which you will exchange for an access token.
account The unique domain for the Evance account. For example, example.evance.me.
Note, this is not the live/preferred domain for the Account. 

 

For example:

https://www.example.com/callback?state={state}&code={code}&account=example.evance.me


4. Exchange the authorisation code for an access token and ID token

You may exchange your one-time authorizaton_code for an access_token by making a POST request to the following URL.

POST https://{domain}/oauth/token.json


The request must include the following parameters in the POST body:

client_id Your App's OAuth 2.0 Web Client client ID.
client_secret Your App's secret key from your OAuth 2.0 Web Client credentials.
redirect_uri An authorised redirect URI specified for your App.
grant_type authorization_code
code The code supplied by the authorisation process above.

 

The actual request might look like the following:

POST /oauth/token.json HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

code=423583y4ht34tu489t4jg&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//www.example.com/callback&
grant_type=authorization_code


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

{
    "access_token": "43e213757dd5a224ace6ffc22b8c436219c5830b",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "59461d2abd392f2c6fd36de836f0660ac6214ee5",
    "id_token": "36f066...d392f"
}

access_token This is the token you will use to interact with API endpoints.
expires_in Represents the lifetime of the Access Token in seconds. Our Access Tokens expire after a period of 1 hour. 
token_type The token type establishes the security requirements when utilising the token. 
id_token A JWT ID Token that contains identity information about the user that is digitally signed into your Evance website.
refresh_token The refresh token has a lifespan of 60 days and may be used to refresh your access token when it expires after 1 hour. 


5. Obtain user information from the ID token

An id_token is a JWT (JSON Web Token), which is a cryptographically signed Base64-encoded JSON object. Usually, it is essential to ensure the JWT is valid before using it. Many JWT libraries will do this for you. But, since since you've just communicated directly with Evance over HTTPS you can be confident the token is valid. 

The ID token's payload

An ID token is a JSON object containing a set of name/value pairs. For example:

{
    "iss": "example.evance.me",
    "sub": 12345,
    "aud": "4231589fhq3th3t.0.app.evance.me",
    "exp": 1353604926,
    "iat": 1353601026,
    "auth_time": 1353601026,
    "nonce": "36f066"
}

iss The Evance Account domain. Note, this is not your preferred/live domain. 
sub The unique Contact ID of the User on Evance.
aud The client_id of your OAuth 2.0 Web Client credentials.
exp The expiration time on or after which the ID token must not be accepted. Represented in Unix time (integer in seconds). 
iat The time the ID token was issued. Represented in Unix time (integer seconds).
nonce The value of the nonce supplied by your app in the authentication request. You should enforce protection against replay attacks by ensuring it is presented only once. 

Note: Evance's implementation of OpenID Connect is temporarily incomplete. Obtaining additional user information should be done using the Contacts API using an OAuth 2.0 Server Key for a Private App. This is a short-term issue. This section with be updated once this issue has been resolved. 

6. Authenticate the user

After obtaining user information from the ID token, you should query your app's user database. If the user already exists in your database, you should start an application session for that user.

If the user does not exist in your user database, you should redirect the user to your new-user sign-up flow. You may be able to auto-register the user based on the information you receive from Evance. Or, for Private Apps where the website is part of the same organisation you may be able to auto-register the user within your website. 

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