Deploy Identity Services

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 login 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 user’s portable identities can used by any third party site that has implemented an OpenID consumer system or through Janrain Social Login. Both implementation methods are described below.

Glossary

Prerequisites

Configuration Parameters 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 Customer This is the home page of the customer used internally by Janrain to identify the customer configuration.
Api Key Janrain A 32-character string, used by the Authenticating Website to identify itself. Janrain will provide this. 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

There are five steps of the Identity Services authentication flow, as illustrated in Figure 1:

  1. INITIATE — RP initiates login by redirecting the user to Janrain’s Identity Services.
  2. GET — A GET redirect to the AW (Authenticating Website).
  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, 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, they will need to redirect the user to the OpenID endpoint, and include all necessary OpenID parameters. For more information on this redirect, see the appendix.

Step 2:  GET

Identity Services will redirect the user’s browser to the Authenticating Website with a GET request and a set of parameters. The Authenticating Website 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:

Example GET request sent from Janrain to Authenticating Website:


http://localhost/login.php?realm=http://localhost/&request_id=123456&requested_attributes=sreg_nickname,sreg_email,sreg_fullname,sreg_dob,sreg_gender,sreg_postcode,sreg_country,sreg_language,sreg_timezone

Step 3:  Open UI

The Authenticating Website 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, then they should be presented with a password screen, as 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 their password correctly).

Step 4:  POST

The Authenticating Website needs to send a POST HTTPS call to PostBack Url. The data payload will be made up of the following:

Mandatory Values

  1. request_id — The request identifier sent from Janrain in step 2.
  2. api_key — You receive your API key from Janrain.
  3. no_prompt — If this value is set to false, Identity Services displays a confirmation page that asks for confirmation to log into the RP and for permission to send user data. If this value is set to true, then the Identity Services does not show a confirmation page to the user.

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

Additional Values

  1. username — The username of the authenticated user. Do not send this parameter if the service sends a cancel.
  2. cancel — The presence of this parameter means that either the user did not authenticate or your website did not authenticate. The authentication transaction should be canceled.

Optional Values

The Authenticating Website may send back the information requested by the RP or Janrain in step 2. A complete list of the requested values is listed below:

Step 5:  Response

Identity Services will send back a response back to the Authenticating Website. 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 Authenticating Website must redirect the user back to the 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 whether they would like to share their user information. See Figure 3:

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 Janrain 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 Janrain Social Login, the RP will need to handle the OpenID response returned to them. An example response is in the appendix.

Example

Here’s an example of Identity Services implemented in Ruby. Ruby is used for sample clarity.

def Janrain_login(user, request_id, remember_me, auth_method)
http = Net::HTTP.new POST_BACK_URL, Net::HTTP.https_default_port
http.use_ssl = true
query_data = {
'request_id' => request_id,
'api_key' => Janrain_KEY,
'no_prompt' => 'true',
'username' => user.id,
'sreg_email' => user.attributes['email'],
'blob' => "remember_me=#{remember_me}&auth_method=#{auth_method}"
}
query_data = query_data.collect{ |key,value| "#{key}=#{CGI.escape( value.to_s )}"
}.join(Service&Service)

http.request_post("/ows_auth", query_data, {'User-Agent' => 'JanRainProServ/1.0
(Automated)Service'})

redirect_to "https://#{RETURN_TO_URL}?request_id=#{params[:request_id]}"
end

def Janrain_cancel(request_id)
http = Net::HTTP.new POST_BACK_URL, Net::HTTP.https_default_port
http.use_ssl = true
query_data = {
'request_id' => request_id,
'api_key' => Janrain_KEY,
'no_prompt' => 'true',
'cancel' => 'true'
}

query_data = query_data.collect{ |key,value| "#{key}=#{CGI.escape( value.to_s )}"
}.join(Service&Service)

http.request_post("/ows_auth", query_data, {'User-Agent' => 'JanRainProServ/1.0
(Automated)Service})

redirect_to "https://#{RETURN_TO_URL}?request_id=#{params[:request_id]}"
end

Appendix

If an RP is not using Janrain Social Login, they must initiate the login (Step 1) and handle the response (Step 8) themselves. Provided are examples of each step:

Step 1

This is a generic redirect to the Identity Services endpoint that starts the OpenID flow:


https://demo.opx.janrain.ws/server?

openid.ns=http://specs.openid.net/auth/2.0&
openid.claimed_id=http://specs.openid.net/auth/2.0/identifier_select&
openid.identity=http://specs.openid.net/auth/2.0/identifier_select&
openid.return_to=http://localhost/&
openid.ns.sreg=http://openid.net/extensions/sreg/1.1&
openid.mode=checkid_setup&
openid.sreg.optional=nickname,email,fullname,dob,gender,postcode,country,language,timezone

Step 8

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


http://localhost/?openid.assoc_handle={HMAC-SHA1}{50ff6f14}{eeyFTg==}&openid.claimed_id=https://stoich-test.opx.janrain.ws/user/foo&openid.identity=https://stoich-test.opx.janrain.ws/user/foo&openid.mode=id_res&openid.ns=http://specs.openid.net/auth/2.0&openid.ns.sreg=http://openid.net/extensions/sreg/1.1&openid.op_endpoint=https://stoich-test.opx.janrain.ws/server&openid.response_nonce=2013-01-23T05:03:16ZVZmdZ2&openid.return_to=http://localhost/&openid.sig=FQLYB5dh2o0wnSwFJbhViStA5R8=&openid.signed=assoc_handle,claimed_id,identity,mode,ns,ns.sreg,op_endpoint,response_nonce,return_to,signed,sreg.email&openid.sreg.email=myname@idp.com