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}&nonce={nonce}&scope={scope}&state={state}

{domain} The live/preferred domain for your website.

response_type In a basic authorization code flow request this should be code.

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. If this value doesn't match an authorized URI, the request will fail with a redirect_uri_mismatch error.

nonce A random unique unguessable string/number generated by your App for the authorization request.

scope A space separated list of Scopes. You must include the openid as a scope to obtain an id_token. A basic request should include openid email as your scope requested, but you may also include the any of the following scopes: email Will include the email and email_verified claim. profile Will include the family_name, given_name, name and picture claim. phone Will include the phone and phone_verified claim if the user's phone number is available and will be omitted from the id_token if not. address Will include the address claim if the user has a primary address available and will be omitted from the id_token if not.

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. For example:

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

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.

 

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 Must be set to 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",
    "email": "just@example.com",
    "email_verified": true,
    "reference": "MYID-84320"
}

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.

email The user's email address is provided when your scope includes the email scope value.

email_verified true if the user's email address has been verified, otherwise false.

family_name The user's surname or last name may be provided when the request includes the profile scope.

given_name The user's first name may be provided when the request includes the profile scope.

name The user's full name in displayable form may be provided when the request includes the profile scope.

picture The URL of the user's profile picture may be provided when the request includes the profile scope.

phone The user's phone number may be provided when the request includes the phone scope.

phone_verified true if the user's phone number has been verified, otherwise false.

address The user's primary address may be provided when the request includes the address scope. The address is returned as an object with the following properties: formatted The formatted address where address lines are separated by a newline character (\n) - based on the country's address format rule (if available). street_address Consists of the address lines 1, 2 and 3 separated by a newline character (\n) as appropriate. locality Represents the town/city of the address. region The state/province/county name for the address may be present. postal_code The zip/postcode for the address may be present. country The name of the country.

reference In addition to the sub property, a user may also be identified by a reference string if set manually by an Administrator or null if not.

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.