Deploy Identity Services

Contents

Janrain Identity Services offers websites the ability to become a custom OpenID Identity Provider using the site’s existing user authentication framework. This functionality allows existing users to log in using their pre-existing username and password, and when used in conjunction with Janrain Social Login and Single Sign-on features, subsequently be recognized automatically by the site’s entire ecosystem of websites and partner properties.

How It Works

Your website holds the parent user database and Janrain Identity Services works behind the scenes, enabling your site to issue portable identities to your users. Identity Services integrates with your website through standard web redirects and HTTPS calls.

Your users’ portable identities can be used by any third party site that has implemented an OpenID consumer system or through Janrain Social Login. Both implementation methods are described in the following sections.

Glossary

Prerequisites

Configuration Parameter Provided by Description
OpenID Identifier Janrain or Customer The OpenID endpoint used to initiate the login. This is provided by Janrain, but custom customer endpoints can be substituted if needed. If a custom endpoint is used, this needs to be provided by the customer to Janrain prior to configuration. Example: https://demo.janrainfederate.com
Home URL (optional) Customer Optional

The home page of the customer used internally by Janrain to identify the customer configuration. If this is not present the base URL of the verify URL will be used to identify the customer configuration. This is only used for identification; it does not impact the user experience.

Api Key Janrain A 32-character string used by the Authenticating Website to identify itself. Janrain will provide this.

Warning: This key is private and should not be disclosed.

PostBack URL Janrain The Authenticating Website will POST to this URL after authenticating the user.
Verify URL Customer The endpoint used to validate the end user. Identity Services will send a GET to this URL with the authentication request.
Return Url Janrain The customer will redirect the user to this URL after receiving confirmation of successful receipt of user data from Janrain.

Identity Services Authentication Flow

These are the steps of the Identity Services authentication flow:

  1. INITIATE — RP initiates login by redirecting the user to Janrain’s Identity Services.
  2. GET — A GET redirect to the AW.
  3. UI — The AW performs interaction to authenticate (ask for password).
  4. POST — AW performs an HTTPS POST to Janrain’s Identity Services.
  5. RESPONSE — Janrain returns an HTTP status to the AW (200 or retry).
  6. REDIRECT — The AW performs a redirect to Janrain’s Identity Services.
  7. OPTIONAL — If no_prompt is set to false, the end user has the opportunity to decline that user data is sent to RP.
  8. RESPONSE — Janrain will redirect the user to the RP with an assertion of success or failure.
Convention login integration

Figure 1: Traditional Login Integration

Step 1: Initiate

The RP initiates login by redirecting the user to Janrain’s Identity Services.

If the RP is using Janrain Social Login, the RP accomplishes this by adding the OpenID button to Social Login.

If the RP is not using Janrain Social Login, the RP must redirect the user to the OpenID endpoint and include all necessary OpenID parameters. For more information on this redirect, see this topic’s Appendix.

Step 2: GET

Identity Services will redirect the user’s browser to the AW with a GET request and a set of parameters. The AW needs to accept the GET from the user’s browser at the Verification URL and will need to save or process some of these parameters:

Here is an example GET request sent from Janrain to the AW:

Step 3: Open UI

The AW must determine if user interface interaction is necessary. For example, if the user is already logged in, then no UI may be necessary. If the user is not logged in, the user should be presented with a password screen (like the one shown in Figure 2).

Conventional login screen

Figure 2. Traditional Login Screen

Note: Proceed to step 4 only if the user has successfully authenticated (entered the correct password).

Step 4: POST

The AW needs to send a POST HTTPS call to PostBack Url. The data payload contains the following values:

Mandatory Values

Note: Many customers set the no_prompt value to true when using Identity Services between a set of trusted sites, where user permission has already been implicitly granted.

Additional Values

Optional Values

The AW may send back the information requested by the RP or Janrain in step 2. The following is a complete list of the requested values:

Step 5: Response

Identity Services will send a response to the AW. This response status must be 200. If you receive anything other than a 200 status, the status should be logged and the transaction stopped. A text error message will be included in the response body, but it is not intended for end user presentation. The only error that can be shown to the user at this point is that the authentication transaction did not complete. It is valid for the AW to pause and retry (starting at step 3) multiple times, but this is not an endless loop.

Step 6: Redirect

The AW must redirect the user back to Identity Services at the Return Url supplied by Janrain. Identity Services expects the authenticated request ID to be provided in one of the following ways:

Step 7: Optional

If no_prompt is set to false, the user will be prompted to approve login to the RP and be asked to share user information.

Figure 3: Login Approval

Figure 3: Login Approval

Step 8: RESPONSE

Janrain will redirect the user back to the RP with an assertion of success or failure.

If the customer is using Social Login, the user will be directed to the RP and Janrain will create and return an access token that can be used to retrieve user information (per the standard Social Login process).

If the customer is not using Social Login, the RP must handle the returned OpenID response. The Appendix contains an example response.

Example

The following code sample is a Ruby implementation of Identity Services.

Appendix

If an RP is not using Social Login, the RP must initiate the login (step 1) and handle the response (step 8).

Step 1

The following code sample is a generic redirect to the Identity Services endpoint that starts the OpenID flow.

Step 8

This is a generic response from the Identity Service that the RP must parse to obtain the user information and OpenID claim.