Overview

Janrain’s Single Sign-On (SSO) functionality enables your customers to register or log in once and effortlessly navigate across your multiple websites without needing to log in again. SSO is also available for Social Login.

By default, Single Sign-On authenticates all users who visit a member site who have an active SSO session open. Using segments, you can implement a more fine-grained SSO experience on your sites. If no segment setting is present, all users with an SSO session are automatically signed in to all customer sites.

For example, a large music brand can segment by artist and associated online stores. This lets a user log into a band’s site and SSO automatically signs the user into an online store in the same segment, but not into another artist’s site.

Multiple segments may be supported on a site. For example, a holding company with many brands may segment SSO by each brand and also allow users who have logged in on any brand’s site to be automatically logged in on the primary holding company site.

Segment settings are stored locally, and end users may manipulate their segment identifiers, so this feature should not be used for site security or restricting access.

Single Sign-On for the Registration UI

This topic discusses how to implement the SSO solution for a family of websites using the Registration UI.

Enable Required JavaScript Settings

SSO is configured in the JavaScript settings that you implement for Registration. The following settings must be enabled on all sites within your SSO network:

  janrain.settings.capture.federate = true;
  // The federateServer URL will be provided by Janrain.
  janrain.settings.capture.federateServer = 'https://example.janrainsso.com';
  janrain.settings.capture.federateXdReceiver = 'https://mysite.com/xd_receiver.html';
  janrain.settings.capture.federateLogoutUri = 'https://mysite.com/logout.html';

Set Up XD Receiver URLs

Each site needs to host a static XD receiver (cross-domain receiver) page. 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 SSO may not work in some browsers.

The following script must also be added to the federateXdReceiver page:

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

Set Up Logout URLs

Each site needs to host a static SSO logout page. The page is never visible to the end user. The SSO logout page for each site should reside on the same domain as the main site, or SSO may not work in some browsers.

Enable Optional JavaScript Settings

There are several optional settings that may be enabled as well. The following example shows how to configure segments to create groups of sites between which to enable SSO.

  janrain.settings.capture.federateSegment = 'segment_1';
  janrain.settings.capture.federateSupportedSegments = ["segment_2","segment_3"];

Handle SSO Logins

Once a user has logged into one of your sites, Janrain will automatically log that user into any other SSO-enabled site that he or she visits. Both the onCaptureLoginSuccess and the onCaptureFederateLogin events will fire with the ssoImplicitLogin property set to true to identify the login event with SSO. This gives you the option to treat logins via SSO differently.

Single Sign-On for the Registration APIs

This topic discusses how to implement the SSO solution for a family of websites implemented using the Registration APIs only (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 sessionalready exists. The check_session method takes an object as an argument. See below for a list of available parameters and an example call.

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

Parameters for check_session

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.
callback_failure Function to call on failed set_session.
callback_success Function to call on successful set_session.
capture_error Function called when a Capture error occurs.
capture_success Function to call on successful Capture response.
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.
segment Site-defined SSO segment as a string.
supported_segments Dash-separated list of supported segments for this site.

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 callback_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_session();

Parameters for end_session:

Parameter Required Description
callback Required Function to be called instead of redirecting to logout_uri.
Scroll ↓