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.

Here, we focus primarily on authorization response handling, access tokens and ID tokens, as well as retrieving user profile data.

Step 1: User authentication process

The user authenticates via traditional crdentials (email and 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.

You must 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 authentication is successful, the response contains an authorization code. If the authorization is not successful (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 tokens

After the web server receives the authorization code, it can exchange the authorization code for an id_token and access_token with a request to the token exchange 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.

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;
      }
    );
  }
);