Authentication (Single-page application)

ReachFive supports and recommends to use Authorization Code Flow with Proof Key for Code Exchange (PKCE) for all apps: native, mobile apps, and Single Page Apps.

The ReachFive Identity SDK facilitates the PKCE implementation by handling the generation of the code verifier and code challenge. The SDK hashes the Code Verifier using S256 as the code challenge method.

Configure a PKCE client in the ReachFive Console

Create an Identity client with your settings, and pay attention to the steps below which are specific to PKCE:

Select None under Token Endpoint Authentication Method.
Under Allowed Callback URLs, add your redirect URI (for example https://www.example.com/login/callback)
Select the Enforce PKCE security for authentication with the authorization code flow checkbox.
Make sure to whitelist all domains where the ReachFive SDK will be used under Allowed Origins (CORS), and click Save (in this example, https://www.example.com/).

User authorization

Use the Identity SDK loginWithPassword command where redirect_uri is the URL that ReachFive uses to intercept the authorization code once authorization has been granted by the user:

client.loginWithPassword({
  email: 'john.doe@example.com',
  password: 'N5uiKvve',
  auth: {
    redirectUri: 'https://www.example.com/login/callback'
  }
})

The code is appended to the query string in the response:

https://www.example.com/login/callback?
code=2_7XpDCeGr61qGKioLUXiXREPd-sUXpegmL4KrFe6pQn9AMqabRogSHOOkeJb27P3pmOudD6adEJAWJ6ZoX-DTrVir-DTCmY_jmiI2S3JO2bAJ87z1ZgAkxY588jbOAkCyKxRrnOG9s9GjUbZr5KcmESmbwnzeI837Jm1oUEh8KB198bnsTmo2io5KuUOk_cAiB-tgSeyX3T2ZSH2MeSLKAqoWmBW9O4t3iBsDl_zVhHJJxjxa-uU_DGsQ5G1v5FShA87mJh9LXJrnOYnk1dohjA__smcc8v6NKysNIbl7f2DAuHWKUdILOfepVutxkq25fqFSnmbFC2wXtraxLbxmxZjLUAOUVzbEFXU99IGTvRvJ8kzgBx232jS17LPnrQcMjzXuzvdWjv6Q23gV2197sLsYPZSxV1hvVsobgmRT4

Get an access token

Use the Identity SDK exchangeAuthorizationCodeWithPkce command:

client.exchangeAuthorizationCodeWithPkce({
  code: '2_7XpD...bgmRT4',
  redirectUri: 'https://www.example.com/login/callback'
})

The redirectUri must be the same as in the previous step.

The command returns an access token:

{
  "access_token": "tb37Sz...h3eh6q",
  "id_token": "eEoQAi...yJ04ae",
  "refresh_token": "djnxBN...eXbEbL",
  "token_type": "Bearer",
  "expires_in": 86400
}

You can inspect the access_token using the Introspection endpoint.

After user authentication

Send ID Token to server

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://YOUR_BACKEND_URL');
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.onload = function() {console.log('Signed in as: ' + xhr.responseText);};
xhr.send('idtoken=' + idToken);

Verify Token on the backend side

ID Tokens are signed using the JSON Web Token (JWT) open standard which defines a compact and self-contained way for securely transmitting information between parties.

Use a JWT library to verify your ID Token and get the payload.

Here is an example of a decoded ID Token:

{
  "aud": ["AtnY5xDg4fbanentihip"],
  "authType": "facebook",
  "birthdate": "1983-11-13",
  "email": "john.doe@example.com",
  "emailVerified": true,
  "exp": 1512225317,
  "familyName": "Doe",
  "gender": "male",
  "givenName": "John",
  "iat": 1512138917,
  "iss": "https://example.com",
  "locale": "en_US",
  "name": "John Doe",
  "newUser": false,
  "picture": "https://graph.facebook.com/10154500298019865/picture",
  "profile": "https://www.facebook.com/app_scoped_user_id/10154500298019865/",
  "sub": "AVqvOB58Fg6nZfQ0ZqXt",
  "updatedAt": "2017-12-01T14:35:17.218Z"
}

See ID Token Payload. NEED MODELS

For security reasons, you must check the following elements for each decoded ID Token:

aud: Audience. It should contain your ReachFive Client ID.
iss: Issuer. It should be equal to your ReachFive Domain URL.
exp: Expiration time. It should not be exceeded.

Do not accept user IDs without checking them. You must use a verified ID Token to securely get the user ID.

For a server to server integration, refer to Authentication for Web App.