Single Sign-On for the Registration APIs

This article discusses how to implement the Single Sign-On (SSO) solution for a family of websites implemented using only Registration APIs (rather than using the Registration UI).

Load the SSO Library

Janrain has provided a library to enable SSO for Registration API implementations. You’ll need to load this file on any page that you wish to enable for SSO.

Load this file either by directly importing the contents of the code from the link above, or by adding a script tag like this:


<script src="http://d1v9u0bgi1uimx.cloudfront.net/static/sso_lite.js"type="text/javascript"></script>
        

Set Up XD Receiver URLs

Each site needs to host a static XD receiver (cross-domain receiver) page, which is used to securely pass the token to the token_uri through JavaScript. The page is never visible to the end user. The XD receiver page for each site should reside on the same domain as the main site, or Single Sign-On may not work in some browsers.

The following code must be included on the XD receiver page:


<html>
<script src="https://d1lqe9temigv1p.cloudfront.net/js/lib/xdcomm.js"type="text/javascript"></script>
</html>
        

Check for Existing SSO Session

On page load, run the check_session method to initiate login if the user session already exists. The check_session method takes three parameters: a config object, the supported segments list, and the segement to set.

Parameters for check_session

Parameter

Required

Description

config

Required

An object that contains the application and SSO settings to check against.

supported_segments

A dash-separated list of segments that the current site is allowed to federate with using SSO. This parameter corresponds to the janrain.settings.capture.federateSupportedSegments JavaScript setting used in Registration UI implementations.

segment

A string that specifies which segment the current site belongs in. This parameter corresponds to the janrain.settings.capture.federateSegment JavaScript setting used in Registration UI implementations.

Parameters for check_session config object

Parameter

Required

Description

client_id

Required

The Capture client ID making the request.

flow_name

Required

The name of the flow configured with the login experience you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in Registration UI implementations.

flow_version

Required

The version number of the flow set in the flow parameter. This parameter corresponds to the janrain.settings.capture.flowVersion JavaScript setting used in Registration UI implementations; however, this call will not accept a version of HEAD as the setting does.

locale

Required

The code for the language you want to use for the login experience. This parameter corresponds to the janrain.settings.language JavaScript setting used in Registration UI implementations.

redirect_uri

Required

This is the address used by the UI to make the redirect for any functions called. This parameter corresponds to the janrain.settings.capture.redirectUri JavaScript setting used in Registration UI implementations.

sso_server

Required

The fully-qualified URL of the SSO server.

xd_receiver

Required

The fully-qualified URL of the cross-domain receiver for this site.

bp_channel

The backplane channel ID. The default value is an empty string.

capture_success

Function to call on successful SSO session initiation.

capture_error

Function called when a Capture error occurs.

callback_success

Function to call on successful set_session.

callback_failure

Function to call on failed set_session.

logout_uri

The fully-qualified URL of the logout page for this site. The default value is undefined.

refresh

Refresh login with Capture even if user currently has an active session. The default value is false.

response_method

Values are jsonp (the default value) or redirect.

response_type

Values are code or token. The default value is token.

Example:


JANRAIN.SSO.check_session(
  {
    client_id:"capture_client_id",
    flow_name:"my_flow_name",
    flow_version:"20160100000000000000",
    locale:"en-US",
    redirect_uri:"http://localhost/",
    sso_server:"https://my_sso_server.janrainsso.com",
    xd_receiver:"http://my_xdr_URL",
    capture_success:function(data){
      //Start session here
    },
  },
  'segment1-segment2',
  'segment1'
);
        

Handle check_session Response

If a user’s session is found, the user’s access token and any profile attributes included in the userData object in the flow will be available (as shown below) from the capture_success parameter:


{
  "data": {
    "stat": "ok",
    "result": {
      "status": "success",
      "statusMessage": "gotSSOCode",
      "transactionId": "12345678",
      "action": "ssoSignin",
      "oneTime": false,
      "userData": {
        "email": "testuser@domain.com",
        "displayName": "User Name",
        "uuid": "12345678"
      },
      "keepMeLoggedIn": false,
      "accessToken": "1a1a1a1q",
      "ssoImplicitLogin": true,
      "renders": false
    }
  }
}
        

If the user session does not already exist, authenticate the user using one of the following API calls:

Sample response:


  {
    "capture_user": {
      "created": "2016-04-20 17:02:18.649505 +0000",
      "uuid": "67890def-6789-defg-6789-67890defgh67",
      // additional profile data...
    },
    "is_new": false,
    "stat": "ok",
    "access_token": foo
    "sso_code": bar
  }
        

Create SSO Session

Using the sso_code returned from a successful authentication, run the set_session method.


JANRAIN.SSO.set_session("bar");
        

Parameters for set_session:

Parameter

Required

Description

sso_code

Required

Capture SSO code reference.

End SSO Session

After logging the user out, run end_session to attempt to log the user out of all sites the user is logged in to.

The logout feature is best-attempt, as the function relies on an open browser to complete the logout. Since this is a client-side solution, if the user closes their browser before all of the logouts can be called, the user may still be logged in to some sites.

If you want to ensure a full sign-out action, you may need to implement a custom server-side solution that manages a user’s SSO sessions.


JANRAIN.SSO.end();
        

Parameters for end_session:

Parameter

Required

Description

callback

Required

Function to be called instead of redirecting to logout_uri.