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.

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 ↓