Server-Side Authentication

Note: Server-Side Authentication requires a page refresh. If your login page is media rich, the refresh will be resource expensive and time consuming, so you might want to use client-side authentication instead.

For Server-side Authentication, the widget requires a file where it POSTs the One-Time Token, and where your apiKey is accessible for making API calls to Engage. This file is referred to as the Token URL Page, because it receives the token from Engage. You need to add the path to this page to the widget code.

You can use janrain.settings.tokenUrl to add the path to the widget code.

The Token URL receives an HTTP POST request with a single parameter, token.

Creating a Server-side Token URL ¶

You can build the Token URL page with any number of web technologies, as long as it can perform these basic steps:

Provide the API Key — The API 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 Token URL file when needed.
Accept the One-Time Token — When the widget accesses the Token URL page, it POSTs a One-Time Token for the session to the page. The file needs to store this token for the auth_info call, or other API calls to the Engage Servers.
Request Profile Information — Using the API Key, and the One-Time Token, use the auth_info call to request profile data from Janrain Engage.
Parse Returned Data — The auth_info call returns profile information in either JSON or XML form.

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, and 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.

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

Figure 1: API Key Location

Step 2. Accept the One-Time Token ¶

This PHP example retrieves the token and assigns it to a variable.
$token = $_POST['token'];

Step 3. Request Profile Information ¶

Once your application has the API Key and the One-Time Token, it is ready to make the call to the Engage API. As with all RESTful calls, this consists of an HTTP request. In this case, we need to make an HTTP POST to the URL for the auth_info function.

In this example, we use PHP with the cURL library to perform the HTTP POST request.

$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);
$resultString = curl_exec($curl);

The result is a string, in either JSON or XML format. The example above retrieves the default format, JSON.

For more on auth_info, see the API reference.

Step 4. Parse Returned Data ¶

The object returned by auth_info can contain a number of object fields; these vary depending on the identity provider and your service level. The one field 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.

If you call auth_info with the default JSON format, you can easily convert the return value to a JSON object:
$result = json_decode($resultString);
The profile object always includes a string field called identifier. The exact format of this field varies from provider to provider, but any given application is guaranteed to get a unique identifier value for each user. That makes the identifier field ideal to use as a key value for user records. Note that the identifier field is not guaranteed to have the same value for the same user and provider combination on all applications; do not share the identifier between applications.

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

Complete Example ¶

This example pulls together the previous examples, adds error handling code, and uses the profile data to display the user’s name.

<html>
    <head>
        <title>Example Application Landing Page</title>
    </head>
    <body>
        <h1>Example Application Landing Page</h1>
<?php
    $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);
    $profileString = curl_exec($curl);
    if (!$profileString){
        echo '<p>Curl error: ' . curl_error($curl);
        echo '<p>HTTP code: ' . curl_errno($curl);
    } else {
        $profile = json_decode($profileString);
        if (property_exists($profile, 'err')) {
            echo '<p>Engage error: ' . $profile->err->msg;
        } else {
            session_start();
            if (property_exists($profile->profile, 'displayName')) {
                $_SESSION['userName'] = $profile->profile->displayName;
            } else {
                $_SESSION['userName'] = '(Anonymous Coward)';
            }
            echo '<p>Hi there ' . $_SESSION['userName'] . '!';
        }

    }
    curl_close($curl);
?>
    </body>
</html>

Next Step ¶

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