Deployment Overview

For each new customer deployment, Janrain Professional Services will provision two distinct environments:

  • Development
  • Production

Depending on the Janrain package you have purchased, a Staging environment may also be provisioned. All environments point to the Janrain platform’s production code, but non-production environments are hosted on separate application servers not scaled for production use.

Each Janrain environment consists of:

  • Social Login application(s)
  • Registration application
  • User data storage
  • API clients and settings
  • Flow configurations

More information about these components can be found in the Registration Overview. Each environment may be configured for use with multiple properties and integration points.

The Development environment is used for configuration, integration, and testing during deployment and UAT (User Acceptance Testing). Janrain will also provision a reference implementation pointing to the customer’s Development environment. This working model of the Janrain Registration UI consists of a set of basic HTML, CSS, and JavaScript files hosted on a Janrain server at a customer-specific URL. The source files are also delivered as a .zip file to be used as a starting point for integration.

After the project kickoff, Janrain will provide technical training to the customer’s team on how to use the Janrain Dashboard and APIs for configuration and how the reference implementation is set up. Once Janrain has provided access to the Development environment and reference implementation, the customer is responsible for the following implementation tasks. All application configuration steps may be completed in the Janrain Dashboard or by using Janrain APIs.

  1. Provision New API Clients
  2. Update API Client Settings
  3. Configure Social Providers
  4. Whitelist Domains for Integration
  5. Integrate Reference Implementation Files
  6. Complete Server-side Integration
  7. Configure the Registration Experience

Once the customer has completed configuration on the Development environment and signed off on Configuration Acceptance Testing, Janrain will then provision the Production environment and promote the approved flow(s) and schema(s) from Development to Production. The customer will need to complete some configuration steps outlined above for the Production environment, as well as update production code that is either pointing to the Registration UI or making direct API calls on the back end (server-side) to use Janrain Production environment credentials. See the Production Launch Process section below for more details.

The Reference Implementation

The reference implementation should serve as a guide for integrating the Janrain Registration UI into your own site. The source files may be used as-is, but most customers will make adjustments to the markup and styling during integration. The hosted .zip file will be kept updated along with the hosted site as Janrain makes updates during the configuration phase, so it can be re- downloaded at any time.

The reference implementation also provides a clean, isolated environment for you to test Janrain configurations, so it should be the first place to check when troubleshooting so that you can identify integration vs. configuration issues. All Configuration Acceptance Testing should be completed at the reference implementation hosted by Janrain. Note that Janrain does not provide hosting for these files for production use.

See the following sections for a description of the source files provided. Note that the structure of these files may differ for some customers depending on when the reference implementation was created, but the overall contents will be the same.

HTML Files

Two HTML files are included as part of the reference implementation. These provide the markup for the Registration UI, including screen containers, JTL tags for forms and fields, and references to scripts utilizing the Registration JavaScript API. Detailed documentation on the contents of each screen can be found in the Default Registration Experience.

File Name Description
index.html Includes all screens needed for logged-out users, including registration, login, account merging, password reset, and email verification.
edit-profile.html Includes all screens accessible by logged-in users for profile management functionality.

Scripts Folder

Two scripts are also included as part of the reference implementation and referenced on both of the HTML pages.

File Name Description
janrain-init.js Includes JavaScript settings and events needed to load the Registration UI. Some settings, such as the ones linking the integration to your application, are required. Other settings for things such as locale, styling options, or enabling Single Sign-on are optional. Sample event handlers are included to handle navigation through the reference implementation based on whether the user is logged in with a valid access token. Additional settings and events are documented on the Registration JavaScript API page.
janrain-utils.js Optional JavaScript functions useful for troubleshooting and debugging during integration, such as logging Janrain events in the console or displaying the currently-loaded flow version.

Styles Folder

Two CSS files are also included as part of the reference implementation. These files do not have to be used, but they provide a starting point for modification and extension as you apply your own styles to the Janrain Registration UI.

File Name Description
janrain.css A baseline stylesheet containing Janrain’s default styling for buttons, fields, text, and other elements that may appear in the Registration UI. This file is included in the array for janrain.settings.capture.stylesheets in janrain-init.js, which loads it after all other stylesheets are loaded from the Janrain platform so that default styles are overridden.
janrain-mobile.css A stylesheet extending the janrain.css file to optimize the Registration UI for mobile devices. This file is included in the array for janrain.settings.capture.mobileStylesheets, which should be placed after the stylesheets setting so any styling loaded from that file is overridden for Mobile.

Configuration Acceptance Testing

Configuration Acceptance Testing is a separate process from end-to-end integration testing and user acceptance testing. The objective is to confirm that any configurations made by Janrain have been completed as agreed upon in any configuration documentation the customer approved during the requirements gathering phase. This testing is completed by the customer at the Janrain-hosted reference implementation.

Janrain provides a set of standard test cases for 20+ use cases along with with step-by-step test actions and their expected results. Custom test cases will also be provided for any custom requirements agreed upon in the configuration documentation.

Configuration Acceptance Testing may cover the following types of activities:

  • Verify that the correct fields are shown on each screen (social registration, traditional registration, edit profile, and so on).
  • Verify that the correct validations are applied to each field (length, format, requiredness, and so on).
  • Verify that any select menus include the correct options.
  • Verify that the correct field labels and error messages are displayed in each language.
  • Verify that the new records are created with all of the necessary data captured by checking in the Registration Dashboard.
  • Verify social and traditional login work as expected for existing records.
  • Verify that any post-login screens are displayed as expected (gating based on age, email verification, acceptance of legal terms, and so on).
  • Verify that data is updated correctly from the edit profile screen.

Because all styling and screen layout will be controlled on the customer’s site, Configuration Acceptance Testing should not cover the following types of activities:

  • Styling/layout of the widget.
  • Client-side functions for validation or navigation.
  • Client-side content gating.
  • HTML-controlled messaging/navigation on the reference implementation.

Configuration Acceptance Testing may start off with a screenshare for the Janrain project team to demonstrate that the reference implementation matches the configuration documentation and satisfies the test cases. The customer will either confirm acceptance of the configuration or provide Janrain with a list of specific changes needed to satisfy the configuration requirements. Once the follow-up items are completed, the project team will notify the customer for final testing and approval.

Step-by-Step Implementation Process

Provision New API Clients

Each website or application that interfaces with the Janrain Registration UI should use its own API client provisioned with the login_client feature. See API Clients and Permissions for more information on the behavior that API clients control.

The reference implementation provided by Janrain is configured with one example API client. The first step to integrating the Registration UI into your site is to create a new API client for your development site.

Update API Client Settings

The second step to integrating the Registration UI into your site is to apply the required settings to your new API client. The following settings are used in the default Registration experience and will need to be implemented for each API client used with the Registration UI:

Some settings may be applied globally to all API clients in the Default Settings section, but many settings such as these control site-specific behavior and should be set on each client individually. Additional settings may be configured in your reference implementation and should be set up on new API clients as needed. Refer to the full list of settings available on the API Client Settings section.

Configure Social Providers

If you are offering social authentication on your sites, the next step to integrating the Registration UI is to configure your social providers. If you only plan to offer traditional authentication, you may skip this step.

Janrain’s Social Login product is embedded within the Registration product, so many of the steps that are documented in Implementing Social Login are handled for you. To enable social providers to be used for login and registration, you will only need to complete the following configuration steps using the Social Login dashboard:

The testing tool available in the dashboard is the first place to test that you have configured each social provider correctly and are requesting the right permissions from users.

When creating an application with social providers that require configuration on their side, it is recommended to use a shared account for your company rather than an individual developer’s account. Janrain will have no access to these applications.

Whitelist Domains for Integration

The next step to integrating the Registration UI into your site is to add your development and testing domains to your Social Login application’s Domain Whitelist setting. This step should be completed even if you only intend to offer traditional authentication.

For security reasons, only whitelisted domains are allowed to communicate with your Social Login application. Note that localhost and your Registration application domain should always be in the whitelist. Janrain will whitelist these for you as part of the provisioning process.

You will then need to add any domains where the Registration UI will be integrated. If you see an error message stating “The token URL or xdReceiver has not been whitelisted” when attempting to initiate a social login, check the domain whitelist to ensure that the site you are currently using is included.

Integrate Reference Implementation Files

Once your development site has been whitelisted, you are ready to begin integrating the source files provided with the reference implementation into your website or application code. These files can be modified as needed to incorporate the Janrain Registration UI into your site’s styling, navigation menus, and session management. Note that Janrain does not provide hosting for any of this content.

  1. Add the janrain-init.js file and, optionally, the janrain-utils.js file to the directory hosting your JavaScript files.
  2. Update janrain.settings.capture.clientId in janrain-init.js to use the new API client created earlier.
  3. Add the following scripts to the <head> of any pages that will be using the Janrain Registration UI, updating the path to the directory where you placed the JavaScript files:

    <script src="scripts/janrain-init.js"></script>
    <script src="scripts/janrain-utils.js"></script>
    
  4. Add the contents of the <body> from the index.html and edit-profile.html files to the <body> of the relevant pages of your site.

  5. Replace the sample event handlers for user navigation copied from the reference implementation as needed to integrate sign in, sign out, register, and profile links into your site’s navigation. See the Default Registration Experience page for details on how to render specific Janrain screens programmatically.

    <a href="#" id="captureSignInLink" onclick="janrain.capture.ui.renderScreen('signIn')">Sign In / Sign Up</a>
    <a href="edit-profile.html?screenToRender=editProfile" id="captureProfileLink" style="display:none">Edit Profile</a>
    <a href="#" id="captureSignOutLink" style="display:none" onclick="janrain.capture.ui.endCaptureSession()">Sign Out</a>
    
  6. Add the janrain.css and janrain-mobile.css files to the directory hosting your CSS files and update as needed to match the styling of the Registration UI to your site.

  7. Update janrain.settings.capture.stylesheets and janrain.settings.capture.mobileStylesheets in janrain-init.js to point to the directory where you placed the CSS files.

From here you can make additional changes to these files to customize the Registration UI, such as adding HTML markup around the JTL tags for forms and fields, reordering JTL tags within a form, defining more Janrain settings and event handlers, or adding custom JavaScript functions.

Complete Server-side Integration

When the Janrain Registration UI is properly integrated into your development environment, users will be able to log in and register just as on the reference implementation. By default, an OAuth access token will be generated upon successful user authentication and stored client-side in the localStorage key janrainCaptureToken. This key indicates to the Registration UI that a user is authenticated and can access profile management screens.

The access token will also be returned in the JavaScript event handlers that Janrain fires upon successful login and registration. Access tokens are valid for one hour, so if your site maintains user sessions for longer periods of time, you can create functions in these event handlers to send the access token to your server, and then create a session for the user and refresh the access token hourly as needed. See Access Tokens and Session Management for more information on this topic.

Below is an example event handler for the onCaptureSessionCreated event, which fires when a user successfully logs in, registers, or completes the email verification process and returns an object containing an access token. As in the example, event handlers must be included within the janrainCaptureWidgetOnLoad function in janrain-init.js, before the start argument.

function janrainCaptureWidgetOnLoad() {

  janrain.events.onCaptureSessionCreated.addHandler(function(result) {
    var token = result.accessToken;
    // Insert code to pass token variable to server
  });

  janrain.capture.ui.start();
}

Alternatively, each scenario in which an access token is generated can be handled differently by targeting one of the events listed below.

Action Event Name
Registration onCaptureRegistrationSuccess
Login onCaptureLoginSuccess
Email Verification onCaptureEmailVerificationSuccess

Configure the Registration Experience

Janrain APIs offer many self-service options for modifying the Default Registration Experience. Below are the most common types of configuration changes that you will want to think about when planning your development cycles. See Customizing Registration for more details on making these configuration changes.

Note that some complex configurations may need to be completed by Janrain, such as adding computed logic to the registration flow, creating new forms and screens, or adding or removing transactional email triggers. If in scope for the project, Janrain will deliver those changes to the customer’s Development environment for Configuration Acceptance Testing on the reference implementation. The customer must sign off on this before making any additional Registration experience configurations.

Production Launch Process

Initial Production Deployment

Janrain will provision a customer’s Production environment when Configuration Acceptance Testing is complete. This environment is distinct from Development with its own Social Login application(s), Registration application, user data storage, API clients and settings, and flow configurations. Janrain will promote the approved flow(s) and schema(s) from Development to Production, but the following configuration tasks completed for Development must also be completed by the customer for Production:

  1. Provision New API Clients
  2. Update API Client Settings
  3. Configure Social Providers
  4. Whitelist Domains for Integration

The customer can then go live with the Janrain Registration UI at any time. Before releasing any website or application code to Production, update all JavaScript settings and direct API calls to your Registration application to point to the Production environment credentials. At a minimum, the following JavaScript settings must be updated:

Setting New Value
janrain.settings.appUrl Production Social Login application domain
janrain.settings.capture.captureServer Production Registration application domain
janrain.settings.capture.appId Production Registration application ID
janrain.settings.capture.clientId Production Registration API client ID
var httpLoadUrl Production Social Login application load file (http site)
var httpsLoadUrl Production Social Login application load file (https site)

In addition, if you have a custom application domain then you will need to replace the rpx_realm API client setting with the rpx_custom_realm API client setting. These API client settings can usually be found in the Default Settings.

If you are using additional features such as Single Sign-on, you may need to update additional settings. The Janrain Professional Services team supporting your deployment can provide guidance on what is required for your implementation.

Additional Production Releases

Once you have launched your first property using Janrain Registration into production, you may continue to update your Registration experience on the Development environment. Many changes can be released to Production on the customer’s side without assistance from Janrain. However, any changes made to the Registration flow using the Configuration API must be promoted to Production by Janrain. Once you have completed testing on Development, open a support ticket with all required information to request a flow to be promoted to Production.

Flow Versioning

By default, your widget is set to show the most recently-published version of the flow from Janrain. However, with each publish, your flow is given a new version number, giving you the ability to use a specific flow version in your implementation and manually change the version, rather than having it update when a new publish happens.

For some, using the default HEAD setting works just fine. This way, any updates to labels, requirements, or functionality made by Janrain will happen automatically once Janrain publishes those changes on the production server. On the other hand, some prefer to apply any flow updates to their own site at a very specific time. For example, to coordinate with a larger set of website revisions, or at the launch of a new product or service.

Setting a Flow Version

The JavaScript setting that dictates the flow version for your Registration widget is called janrain.settings.capture.flowVersion. In the .zip file given to you by Janrain, you can find the flow version setting in the janrain-init.js file.

Checking a Flow Version

If you want to see what the setting value for your janrain.settings.capture.flowVersion is, you can (while looking at a page hosting your widget) open your browser’s development console, type janrain.settings.capture.flowVersion, and press Enter. You should then see the value for that setting.

If the setting is set to HEAD, you were not given a precise flow version. However, there is a way to grab the current flow version number.

Again, in your development console in your browser, you can run the following script:

janrain.events.onCaptureRenderComplete.addHandler(function(result) {
    if (window.console && window.console.log){
        if(result.flow != "" && typeof result.flow != "undefined"){
            if(result.flow.flow != "" && typeof result.flow.flow != "undefined"){
                console.log("Flow Name: " + result.flow.flow);
            }
            if(result.flow.version != "" && typeof result.flow.version != "undefined"){
                console.log("Flow Version: " + result.flow.version);
            }
        }
    }
});

You can also use the Configuration API to find all the flow versions available for a specific flow.

Single Sign-On

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 Single Sign-on (SSO) solution for a family of websites using the Registration UI.

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';

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>

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"];

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 ssoImplicitLogin events will fire with the ssoImplicitLogin property set to true to identify the login event with SSO. This will give you the option to treat logins via SSO differently.

Single Sign-On for the Registration APIs

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

  1. Load the SSO library for Registration APIs

    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.

    To 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>
    
  2. 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>
    
  3. Run check_session

    On page load, run the check_session method to initiate login if the user session already exists. The check_session method takes an object as an argument. This object will contain all of the parameters you want to use to call check_session with. See below for a list of available parameters and an example check_session 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.
    1. 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
          }
        }
      }
      
    2. 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
        }
      
  4. Run set_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.
  5. 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, then they 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 sever-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.

Access Tokens and Codes

Janrain Registration utilizes several OAuth access tokens and codes through both the social and traditional authentication process. Below is an overview of each type of token and the context in which each is used.

Access Tokens

Access tokens are provisioned after a successful authentication through Janrain Registration when the response type is set to token in the JavaScript settings or as an API parameter.

They allow for scoped, time-limited access to the Janrain user profile database through the Registration UI. They may also be used as authentication for some /entity endpoints instead of a client ID and secret.

Access tokens are bearer tokens and are only valid for one hour by default. The lifetime can be configured differently by Janrain Professional Services, but an expiration of longer than one hour is not recommended for security reasons. Access tokens may be refreshed using the oauth/token endpoint or provisioned manually using the access/getAccessToken endpoint.

Authorization Codes

Authorization codes are provisioned after a successful authentication through Janrain Registration when the response type is set to code in the JavaScript settings or as an API parameter. A code must be exchanged for an access token with the oauth/token endpoint for access to the Janrain user profile database.

They are also generated in the reset password workflow and appended to the base URL set in the the password_recover_url client setting. The lifetime of the code in the reset password link is configurable in the recover_code_lifetime client setting.

Authorization codes may also be provisioned manually through the access/getAuthorizationCode endpoint.

Each authorization code is valid for one-time use only.

IDP Tokens

IDP tokens are provisioned by an IDP (Identity Provider) after a successful social authentication. They allow for scoped, time-limited access to user data through the IDP’s APIs. IDP tokens must be converted into a Social Login token with the signin/oauth endpoint for use with Janrain Registration.

Refresh Tokens

Refresh tokens are only returned in the response of a successful oauth/token call when exchanging an authorization code or a previous refresh token for an access token. This allows for infinitely refreshable access tokens.

Each refresh token is valid for one-time use only.

Social Login Tokens

Social Login tokens are provisioned after a successful authentication through Janrain Social Login. They allow for scoped, one-time access to user data through the auth_info endpoint.

These tokens are also used to complete the social authentication process in API-based Registration implementations with the oauth/auth_native, oauth/register_native , and oauth/auth_native_traditional endpoints. For normal login or registration, a Social Login token will be passed into the token parameter, and for an account merge process a Social Login token will also be passed into the merge_token parameter.

Social Login tokens may be provisioned manually using the signin/oauth endpoint in exchange for an IDP token.

Verification Codes

Verification codes are generated in the email verification workflow and appended to the base URL set in the the verify_email_url client setting. The lifetime of the code in the reset password link is configurable in the verification_code_lifetime client setting.

Verification codes may also be provisioned manually through the access/getVerificationCode endpoint.

Each verification code is valid for one-time use only.

Managing Sessions with Registration

Janrain’s Registration UI and Single Sign-On products are client-side web applications that generate Janrain access tokens when a user is authenticated to create a client-side “session”. A Janrain session is only dependent on the presence of a valid access token stored in the user’s browser and is not connected to a server-side session without integration on the customer’s side. The overview and more detailed sections below should help you determine whether server-side session management is required for your use cases. See the Access Tokens and Codes section for more detail on each of the tokens referenced.

Client-side “sessions” may require less integration effort if you do not require server-side integration. However, Janrain does not provide a refresh token client-side, so the “session” will expire unless a new token is generated server-side. Outside of the code-for-token exchange, an API client with the access_issuer feature must be used to generate an access token.

Server-side session management requires more integration effort but is potentially more secure. The user’s access token does not have to be exposed client-side, but if users need to be able to access Janrain profile screens you will need to implement code placing an access token into localStorage when necessary. In the code-for-token exchange, you can use the same API client with the login_client feature client-side for authentication and server-side for refreshing access tokens.

Client-side Sessions

By default, the Janrain Registration UI is configured to return an access token after successful authentication. This is configured by setting the janrain.settings.capture.responseType JavaScript setting to token. With this approach, the access token is returned client­-side and included in the response for the onCaptureSessionCreated and onCaptureLoginSuccess event handlers, and placed in the localStorage key janrainCaptureToken.

An access token being present in localStorage tells the Registration UI that there is an active “session” for the user, which allows access to Janrain screens configured to display user data, such as the editProfile screen.

The client­-side “session” will expire when the access token expires, one hour by default, and refresh tokens are not available for use client-side. In order to access Janrain screens that require an access token, the end user will need to reauthenticate through the Registration UI.

Alternately, the customer can implement server-side logic to extend the client-side “session” on the user’s behalf:

  • After a user successfully logs in, collect the uuid, access token, and expiration time from the onCaptureLoginSuccess event response and store them server-side.
  • When the access token expires, use the uuid to make a server-side call to access/getAccessToken to generate a new access token.
  • Pass the new access token to the client-side JavaScript function createCaptureSession, which will place it in the janrainCaptureToken key along with a new expiration time.

Server-side Sessions

Although it requires a larger integration effort, a “code­-for­-token” solution is ideal for a higher level of security or tight integration with back­end session management. The Janrain Registration UI can be set to return a one-time authorization code rather than an access token by setting the janrain.settings.capture.responseType Javsacript setting to code. With this approach, the authorization code is returned in the response for the onCaptureSessionCreated and onCaptureLoginSuccess event handlers.

The authorization code must then be passed to a server and exchanged for an access token and refresh token, which must be stored in the server session and refreshed as needed using the oauth/token endpoint. With this approach, the access token is not placed in localStorage, which means there is no client­-side “session”.

A customer using the Registration UI can optionally create a client­-side session when performing the code-for-token exchange.

Creating a Client Side Session

When a user interacting with the Registration UI attempts an action that requires an access token (e.g. save profile), the onCaptureExpiredToken, onCaptureInvalidToken, or onCaptureAccessDenied event handlers will fire depending on the scenario. These event handlers can be used to call a server-side script to generate a new valid access token, pass it back to the client-side JavaScript function createCaptureSession, and re-attempt the action.

Refresh an Expired Access Token

To avoid expired access tokens, this server code should be used with each page load (or server request) to check the access token stored in the session and refresh it if it has expired. In this way, the sever session is “managing” the access token and will have a valid access token for as long as the session is valid.

The end­-user can use the Janrain Registration UI to “log out”, which will fire the onCaptureSessionEnded event handler. This can be used to send a request to the server to kill the session.

Scroll ↓