Implementing OpenID Connect Identification with brainCloud

What is OpenID Connect

OpenID Connect is an interoperable authentication protocol based on the OAuth 2.0 framework of specifications (IETF RFC 6749 and 6750). It simplifies the way to verify the identity of users based on the authentication performed by an Authorization Server and to obtain user profile information in an interoperable and REST-like manner.

OpenID Connect enables application and website developers to launch sign-in flows and receive verifiable assertions about users across Web-based, mobile, and JavaScript clients. And the specification suite is extensible to support a range of optional features such as encryption of identity data, discovery of OpenID Providers, and session logout.

For developers, it provides a secure and verifiable answer to the question “What is the identity of the person currently using the browser or mobile app that is connected?” Best of all, it removes the responsibility of setting, storing, and managing passwords which is frequently associated with credential-based data breaches.

OpenID Connect on brainCloud

For security purposes, OpenID Connection flows require a web browser to collect the credentials of the user that is logging in. Those credentials are never seen by the client app (or brainCloud) - which is one of the reasons OpenID is so secure.

The developer's client application is responsible for implementing and initiating the OpenID login flow. The details of this are outside of scope of this document (and our client libs).

Once the login has returned the JWT token - the app should initiate a External Authentication with brainCloud via the AuthenticateExternal() client API call.

The external auth with leverage a custom external auth script - as we as a few key global properties - to perform the authentication.

This diagram describes the overall flow:

External Authentication

External Authentication is a script-based authentication that allows brainCloud to work with essentially any external identity provider - including OpenID Connect.

To use external authentication, the developer writes a custom script that will be used for the purpose - and configures it on the Design > Authentication > External page of the app.

We have provided an example script (that leverages a few global properties for convenience) to perform this authentication.

More information about External Authentication scripts can be found here.

External Auth Script

The following is an example script for performing basic OpenID Connect behaviour. This script should be defined with no client permissions (i.e. client, server and peer callable flags should be set to false).

openIdAuth script

"use strict";

function main() {

  var response = {valid:false}; // by default assume authentication fails

  // jksUri (JSON web keys) - differs greatly by provider - example:
  // https://domain.com/v1/keys
  var jksUri = bridge.getGlobalProperty("oidJKSUri");

  // issuer - will look something like:
  // https://domain.com/oauth2/default
  var issuer = bridge.getGlobalProperty("oidIssuer");

  // audience - the token's audience - will look something like
  // api://default
  var audience = bridge.getGlobalProperty("oidAudience");

  // Verify OID Token
  var identityProxy = bridge.getIdentityServiceProxy();
  var oidResponse = identityProxy.verifySignedJwt(
    jksUri , issuer, audience, data.authenticationToken);


  if ( oidResponse.status == 200 ) 
  {    
    // JWT verification passed - but lets perform a few more checks.
    // The passed in externalId will be used to identify the user.
    // The client can choose to pass in either:
    //   - the user's email address
    //   - or their SUB  
    // We recommend the SUB as it is more resilient.
    var userId = data.externalId; // Okta User Id
    var userIdType ="EMAIL";
    if ( userId.indexOf("@") == -1 ) {
      userIdType ="SUB";
    }

    // Confirm that the externalId matches what is present in the JWT token
    if ( (( userIdType == "EMAIL" ) && ( userId == oidResponse.email )) ||
         (( userIdType == "SUB" ) && ( userId == oidResponse.sub )) ) 
    {
      // The request was successful, and 
      // MATCHED the user who initiated the request
      response.valid = true;
    }
  }
  else
  {
    // The request had an error - it was assumed false by default 
    // No need to set the valid property
  }

  return response;
}

main();

Note that this script calls VerifySignedJwt() as an important part of it's processing. The documentation for that call can be found here.

Associated Global Properties

Of course, the global properties referred to by the script need to be configured for the app. This is done on the Design > Cloud Data > Properties page.

The should all be configured as Strings. And if the values need to change for DEV vs. STAGING vs. PROD instances of your app, be sure to check the [x] Preserve value during deploy option.

---

We hope that helps you in setting up OpenID Connect-based authentication for your brainCloud apps!

So - to summarize, you must:

Create the openidAuth script
Configure the External Identity for the app
Create the global properties that will be used from the app
Implement the OpenID connection functionality in the client app (launching a web interface to perform the login)
Retrieve the JWT from returned from OpenID Connect - and call AuthenticateExternal(), passing it:
- the "sub" id (or alternatively email address) from the JWT in the externalId parameter
- the JWT as the authenticationToken parameter

If you have issues - be sure to hit up our Support Team.

Happy Coding!