Deploy Identity Services

Janrain Identity Services can make your website’s conventional user identities portable and open-standards compliant by wrapping the OpenID standard into a custom identity provider for your organization. Your conventional users can then sign into your website just once and be recognized automatically by your ecosystem of websites and partner properties. Users can also securely share profile data and receive a personalized browsing experience.

Janrain Identity Services also makes implementation much easier for you.

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. To implement this service, the authenticating website needs only to complete the setup configuration, and then implement the authentication web action and the back-channel call.

Definition of Terms

Configuration Parameters Provided by Description
<ApiKey> 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.
<PostBackURL> Janrain This endpoint is used in Integration Step 3.
<VerifyURL> Customer This endoint is used in Integration Step 1.
<ReturnToUrl> Janrain This is the endpoint for the browser redirect in Step 3.

Conventional Login Integration

There are five steps for the conventional user enablement process, as illustrated in Figure 1:

  1. GET — A GET redirect to the AW (Authenticating Website).
  2. UI — Interaction to authenticate (ask for password).
  3. POST — An HTTPS back channel POST to Janrain’s Identity Services.
  4. RESPONSE — The response to the back channel call.
  5. REDIRECT — The responding redirect back to Janrain’s Identity Services.
Convention login integration

Figure 1. Convention login integration

Step 1, Integration (GET)

The AW needs to accept a GET at an arbitrary endpoint defined as the <VerifyUrl> configuration parameter. An example endpoint may be https://service.authsite.com/startauth.html. The GET will contain several parameters:

Example:

https://service.authsite.com/

Step 2, Integration (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, then they should be presented with a password screen, as shown in Figure 2.

Conventional login screen

Figure 2. Conventional login screen

Note: Proceed to Step 3 only if the user has successfully authenticated (entered their password correctly).

Step 3, Integration (POST)

The AW needs to send a POST HTTPS call to <PostBackUrl>. The data payload will be made up of the following:

Mandatory Values

  1. request_id — The value from Step 1.
  2. api_key — You receive your API key from Janrain.
  3. no_prompt — If this value is set to true, then the Identity Services does not show a confirmation page to the user, and the AW should obtain confirmation from the user by other means. If this value is not set to true, the Identity Services does show a confirmation page.

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.

Sharing identity across websites

Figure 3. Sharing identity across websites

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

Integration Step 4, Response

The response status from the back channel call must be 200 to proceed. (See Figure 4.) If you receive anything other than a 200 status, log the status and stop the transaction. 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.

200 response

Figure 4. 200 response

Integration Step 5, Redirect

The AW must redirect the user back to the Identity Services at the <ReturnToUrl> supplied by Janrain; Identity Services expects the authenticated request ID to be provided in one of the following ways:

302 redirect

Figure 5. 302 redirect

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