Client-Side Authentication

Note: Client-Side Authentication avoids the page refresh required by Server-Side Authentication. If your login page is media rich, the refresh will be resource expensive and time consuming, so using the Client-Side authentication method is probably best for you.

Instead of redirecting to a retrieval page (the Token URL page), add a handler for onProviderLoginToken using the addHandler method. Place this code in the onJanrainWidgetOnload function inside your page’s <head> tag. The page must still access the server to retrieve user data, but it can do so using AJAX, avoiding any whole-page refresh. (You can use any technology similar to AJAX, as long as you do not require a page refresh.)

Important: Even though this implementation is totally client side, it won’t work if you load a page using file:///Users/whoever/Desktop/ my_integration.html. You need to load the static page over http. This is because when loading with file:// , the browser will not send a referer header.

Note: Widgets that use client-side authentication need a valid tokenUrl setting, as described in the sections in creating and deploying widgets. This setting is not actually used, but the Engage server requires it for legacy reasons. The value in tokenUrl must be a valid URL and must have a domain that appears in the whitelist. The URL need not point to an actual page.

Setting up Client-side Authentication ¶

Use JavaScript to handle the Client-side Authentication actions. The script needs to include the following steps in order to work.

Provide the API Key — This key is unique to your application, you can find it on your Dashboard. Store your key in a non-public file that can be included in the server page when needed.
Accept the One-Time Token — The onProviderLoginToken event fires when a user successfully logs into an identity provider. The Engage Servers return the token to any handler added for this event.
Request Profile Information — The server side script, using AJAX, makes the auth_info call, along with the API Key, and the One-Time Token to request profile data from Janrain Engage.
Parse Returned Data — The auth_info call returns profile information in either JSON or XML format.

Note: The example given here uses PHP, but you can use other technologies and we provide code samples for several.

Step 1. Provide the API Key ¶

The API Key is unique to your application. You can find it on the Dashboard (see Figure 1). You must keep it secret. For this example, we store the API Key as a variable in a file called api_key.php outside of the web root, so that it remains inaccessible to the public.

Security Issue: If a malicious user acquires your API Key and appId, they could steal data from your site, or even modify your site.

<?php
$apiKey = '0123456789012345678901234567890123456789';
?>

Figure 1: Application Key

Step 2. Accept the One-Time Token ¶

To generate the onProviderLoginToken event, add the following line to your existing widget code generated on the Get the Code page.
janrain.settings.tokenAction='event';
Use this code to provide an event handler that receives an object containing the one-time token.

function janrainWidgetOnload() {
    janrain.events.onProviderLoginToken.addHandler(function(tokenResponse) {
    ...
    })
}

The event handler must still call a server-side script to make the actual auth_info call. (Making the call in client-side code would expose the API key.) This can be done with Ajax, preventing a whole-page refresh. Before we talk about the Ajax call, we need to look at the server-side script itself.

Make sure that you call the page with http:// rather than file:///.

Figure 2. Widget Code Placement

Step 3. Request Profile Information ¶

The server-side script performs the actual auth_info call that retrieves the user’s data. To do this, it needs the application’s API Key and the One-Time Token (passed to the script when called from the sign-in page). As with all RESTful calls, the auth_info call consists of an HTTP request.

The following example is a PHP script that uses the cURL library to perform an HTTP POST request. It’s not meant to be cut and pasted into code as is, but more to illustrate how to implement the request. Due to the many ways a website can be built, it is difficult to craft a one-size-fits-all solution.

To keep your API Key secure, store it in a separate file outside the web root, and accessed it only through a require statement.

Here is the script, which retrieves and returns the user record as a JSON object. On failure, it generates a JSON object describing the failure.

<?php
    header('Content-type: text/json');

    $token = $_POST['token'];
    require '/var/php_include/api_key.php';

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, 'https://rpxnow.com/api/v2/auth_info');
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS,
        array('token' =>  $token,
              'apiKey' => $apiKey));
    curl_setopt($curl, CURLOPT_FAILONERROR, true);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($curl);
    if (!$response){
        echo '{"Curl error": "' . curl_error($curl). '",';
        echo '"HTTP code": "' . curl_errno($curl) . '"}';
    } else {
        echo $response;
    }
    curl_close($curl);
?>

Here’s an example using JQuery.

<script type="text/javascript">
janrain.events.onProviderLoginToken.addHandler(function(response) {
        $.ajax({
                type: "POST",
                url: "profile.php",
                data: "token=" + response.token,
                success: function(res) {
                    $("#results").html(res);
                }
        });
});
</script>

Any AJAX library will work for this, or you can build one from scratch.

Step 4. Parse the Returned Data ¶

The object returned by the auth_info call can contain a number of object fields; these vary depending on a number of factors, including identity provider and service level. One of the fields that is always returned is profile, which contains a normalized version of the user profile provided by the identity provider. Normalizing this profile minimizes provider-specific differences.

The profile object always includes a string field called identifier. The exact format of this field varies, but a given application is guaranteed to get a unique identifier value for each user. That makes identifier ideal for use as a key value for user records. Note that identifier is not guaranteed to have the same value for the same user and provider combination on all applications; do not share the user identifier between applications.

For more information on the profile object, see User Profile Data.

Next Step ¶

Once your server page is in place, the last step is to complete the Call the API page.