Authentication (Web Application)

This article explains how web server applications can implement the authentication process. This flow is based on OpenID and OAuth 2.0 standards.

This article focuses on authorization response handling, access tokens, ID tokens and user profile data retrieval. Other steps are described in other guides depending on your client-side environment.

Step 1: User authentication process

The user authenticates via email/password or social login. This process must be at least partially implemented using the suitable ReachFive SDK depending on the client platform.

ReachFive Identity SDKs allow different authentication flows. For server-side authentication, you must use a code response type, and set your login callback URL in the redirectUri attribute (The URI must be whitelisted in the "Allowed Callback URLs" field of your ReachFive account settings).

For security reasons, you have to list all callback URLs in the Allowed Callback URLs field of your ReachFive console.

reach5('showAuth', {
  container: 'auth-container',
  auth: {
    responseType: 'code', // This is the default value when "redirectUri" attribute is set.
    redirectUri: 'https://www.example.com/login/callback'
  }
});

Step 2: Handle the Authorization Response

After the authentication process, ReachFive responds to your application by redirecting the user to the defined callback URL (redirectUri).

If the authentication succeeded, then the response contains an authorization code. If not (e.g. when the user does not approve access to his social data), the response contains an error message. This information appears in the query string.

An authorization code response:

https://www.example.com/login/callback?code=A8sLD49d-lPcKyUwBaSm4oThfjp4

An error response:

https://www.example.com/login/callback?error=access_denied

Step 3: Exchange authorization code for ID token

After the web server receives the authorization code, it can exchange the authorization code for an ID token using an HTTP request to the ReachFive’s token endpoint.

The string YOUR_REACHFIVE_DOMAIN should be replaced with the domain of your ReachFive account and the string YOUR_REACHFIVE_CLIENT_ID should be replaced with your client ID of your ReachFive account.

For more information, read How-To get your ReachFive Domain and Credentials.

POST /oauth/token HTTP/1.1
Host: https://YOUR_REACHFIVE_DOMAIN
Content-Type: application/x-www-form-urlencoded

code=A8sLD49d-lPcKyUwBaSm4oThfjp4
&client_id=YOUR_REACHFIVE_CLIENT_ID
&redirect_uri=https://www.example.com/login/callback
&grant_type=authorization_code
{
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...",
  "token_type": "Bearer",
  "expires_in": 3600
}

You can inspect the access_token using the Introspection endpoint.

Step 4: Retrieve user profile data from ID Token

After your application obtains an id_token, you can use the token to retrieve the user’s profile data by parsing it. An id_token is a JWT (JSON Web Token), that is, a cryptographically signed Base64-encoded JSON object. As you are communicating directly with ReachFive over HTTPS channel, it is normally not critical that you validate your id_token before parsing it. However, most API libraries combine the validation with the work of decoding the base64 and parsing the JSON.

var decodedToken = jwt.verify(idToken, clientSecret);

Decoded JWT token example:

{
  "sub": "AVPw-jHcQG5c_BvJk9e_",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@example.com"
}

Full example (NodeJS/Express)

var express = require('express');
var request = require('request');
var jwt = require('jsonwebtoken');
var router = express.Router();

router.get(
  '/login/callback',
  function(req, res) {
    if (req.query.error) {
      // Authentication failed
      // Redirect to login page
      return;
    }

    var code = req.query.code; // 'code' query parameter

    // Those informations are available in your ReachFive account's settings
    var domain = 'YOUR_REACHFIVE_DOMAIN';
    var clientId = 'YOUR_REACHFIVE_CLIENT_ID';
    var clientSecret = 'YOUR_REACHFIVE_CLIENT_SECRET';

    // This is the redirect uri corresponding to the current callback
    var redirectUri = 'YOUR_LOGIN_CALLBACK_URL';

    // Send an POST HTTP request using the "application/x-www-form-urlencoded"
    // format to ReachFive's token endpoint
    request.post(
      'https://' + domain + '/oauth/token',
      {
        form: {
          'code': code,
          'client_id': clientId,
          'redirect_uri': redirectUri,
          'grant_type': 'authorization_code'
        }
      },
      function(err, response, body) {
        if (!err) {
          // Unexpected error
          return;
        }
        if (response.statusCode != 200) {
          // Expected error
          // Those types of error can occurred when the authorization code is expired for example.
          return;
        }

        // Success response

        // Parse JSON response
        var authResult = JSON.parse(body);

        // Retrieve id token from response
        var idToken = authResult['id_token'];

        // Parse and validate ID Token
        var decodedToken = jwt.verify(idToken, clientSecret);

        var id = decodedToken.sub;
        var givenName = decodedToken.given_name;
        var familyName = decodedToken.family_name;
        var email = decodedToken.email;
      }
    );
  }
);