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.
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.
|Configuration Parameter||Provided by||Description|
||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:
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.
||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.
||Janrain||The Authenticating Website will POST to this URL after authenticating the user.|
||Customer||The endpoint used to validate the end user. Identity Services will send a GET to this URL with the authentication request.|
||Janrain||The customer will redirect the user to this URL after receiving confirmation of successful receipt of user data from Janrain.|
These are the steps of the Identity Services authentication flow:
no_promptis set to
false, the end user has the opportunity to decline that user data is sent to RP.
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.
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:
request_id— This identifies the request and will need to be returned by the AW in the response to Janrain.
requested_attributes— These are the attributes requested by Janrain Social Login or by the RP. These should be retrieved by the AW and returned in the response to Janrain.
Here is an example
GET request sent from Janrain to the AW:
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).
Note: Proceed to step 4 only if the user has successfully authenticated (entered the correct password).
The AW needs to send a
POST HTTPS call to
PostBack Url. The data payload contains the following values:
request_id— The request identifier sent from Janrain in step 2.
api_key— You receive your API key from Janrain.
no_prompt— If this value is set to
false, Identity Services displays a page that asks for confirmation to log in to the RP and for permission to send user data. If this value is set to
true, Identity Services does not display a confirmation page to the user.
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.
username— The user name of the authenticated user. Do not send this parameter if the service sends a
cancel— The presence of this parameter means that either the user or your website did not authenticate. The authentication transaction should be canceled.
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:
sreg_nickname— Any UTF-8 string that the end user wants to use as a nickname.
sreg_email— The email address of the end user as specified in section 3.4.1 of [RFC2822] (Resnick, P., Internet Message Format ).
sreg_fullname— A UTF-8 string free text representation of the end user’s full name.
sreg_dob— The end user’s date of birth as SERVICE-MM-DD. Any values whose representation uses fewer than the specified number of digits should be zero-padded. The length of this value MUST always be 10. If the end user user does not want to reveal any particular component of this value, it MUST be set to zero. For instance, if a end user wants to specify that his or her date of birth is 1980, but not the month or day, the value returned SHALL be “1980-00-00”.
sreg_gender— The end user’s gender (“M” for male, “F” for female).
sreg_postcode— UTF-8 string free text that should conform to the end user’s country’s postal system.
sreg_country— The end user’s country of residence as specified by ISO3166.
sreg_language— The end user’s preferred language as specified by ISO639.
sreg_timezone— The end user’s timezone, as defined by the Simple Registration specification (which references this site).
blob– You can pass back arbitrary fields through Identity Services by using the
blobfield. The value of this field is a concatenated list of key/value pairs separated by ampersands (
&). See the code example at the end of this topic.
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.
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:
request_id. This is URL-encoded if the user was redirected via a standard HTTP
GET302 (see Figure 5).
request_id. This is www-form-encoded if the user was redirected via a HTTP
no_prompt is set to
false, the user will be prompted to approve login to the RP and be asked to share user information.
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.
The following code sample is a Ruby implementation of Identity Services.
If an RP is not using Social Login, the RP must initiate the login (step 1) and handle the response (step 8).
The following code sample is a generic redirect to the Identity Services endpoint that starts the OpenID flow.
This is a generic response from the Identity Service that the RP must parse to obtain the user information and OpenID claim.