Manage JavaScript SDK single sign-on for the registration APIs

šŸ“˜

The content on this page deals with single sign-on (SSO) using the JavaScript SDK. Due to changes in web browser technology, including the fact that most browsers prohibit the use of third-party cookies, SSO using the JavaScript SDK is no longer available to new Identity Cloud customers. (However, we will continue to support existing customers who use this methodology.) If single sign-on is important to you we recommend that you use An introduction to Hosted Login for your login and registration needs. See our Getting Started Guide to learn more about how single sign-on is implemented in Hosted Login.


This articleĀ details how to implement the Single Sign-On (SSO) solution for a family of websites usingĀ Identity Cloud APIs.

Load the SSO library

ā€‹Akamaiā€‹provides aĀ library to enable SSO for Registration API implementations. You need to load this file on any page you wish to enable for SSO.

Load this file either by directly importing the contents 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 (this 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 might 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 an existing SSO xession

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 segment to set.


Parameters for check_session

ParameterRequiredDescription
configāœ“Object that contains the application and SSO settings to check against.
supported_segmentsDash-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.
SegmentString 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

ParameterRequiredDescription
client_idāœ“Capture client ID making the request.
flow_nameāœ“Name of the flow you want to use. This parameter corresponds to the janrain.settings.capture.flowName JavaScript setting used in Registration UI implementations.
flow_versionāœ“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. Noe that you can't use HEAD as the flow version.
localeāœ“Language code. This parameter corresponds to the janrain.settings.language JavaScript setting used in Registration UI implementations.
redirect_uriāœ“Address used 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āœ“Fully-qualified URL of the SSO server.
xd_receiverāœ“Fully-qualified URL of the cross-domain receiver for this site.
bp_channelBackplane channel ID. The default value is an empty string.
capture_successFunction to call on successful SSO session initiation.
capture_errorFunction called when a Capture error occurs.
callback_successFunction to call on successful set_session.
callback_failureFunction to call on failed set_session.
logout_uriFully-qualified URL of the logout page for the site. The default value is undefined.
refreshIndicates whether the siet should refresh login with Capture even if user currently has an active session. The default value is false.
response_methodValues are JSONP (the default value) or redirect.
response_typeValues 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 are available 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 doesn't have an existing session, 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 an 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

ParameterRequiredDescription
sso_codeāœ“Capture SSO code reference.

End an SSO session

After logging the user out, runĀ end_sessionĀ toĀ attempt to log the user out of all sites they're logged in to.

The logout feature is best-attempt, as the function relies on an open browser to complete the logout. Because this is a client-side solution and a user might close their browser before all of the logouts can be called, the user might remain logged in to some sites.

If you want to ensure a full sign-out action you might need to implement a custom server-side solution that manages a userā€™s SSO sessions.

JANRAIN.SSO.end_session();

Parameters for end_session

ParameterRequiredDescription
callbackāœ“Function to be called instead of redirecting to logout_uri.