Social Sign-In Quick Start Guide

For customers of our JUMP Solution, or Capture Premium, Social Sign-in is included as part of the JUMP starter kit. You will not need to follow these initial steps.

Introduction ¶

The purpose of this guide is to illustrate how to quickly integrate the Social Sign-in Widget (see Figure 1) into an existing website. (You can try this out in a blank web page.) By the end, you’ll have a simple, no-frills dialog box that allows a user to sign in using a social profile and displays the information returned once authenticated.

As Janrain Engage is a powerful and extensible platform, this example is presented as a high-level overview, to get new users familiar with the process. For users seeking more in-depth information on implementation, please see our dedicated Social Sign-in Widget page.

Figure 1: Sign-in Implemented in this Guide

Overview ¶

For adding features to existing websites, Janrain Engage provides a number of widgets that are designed to drop into existing code. In this guide, you’ll design a widget on the Janrain Engage Dashboard. When you finish, the Dashboard will generate JavaScript code that is ready to place on your page, with minimal adjustments.You must have a working web server available to you and permission to read and write to the directories for your web server.

Required tools for this guide:  Janrain Engage Dashboard and PHP5. (Make sure that your PHP5 implementation includes cURL.)

Designing a Widget with the Dashboard ¶

The Dashboard (Figure 2) is located at rpxnow.com. If you haven’t signed up for an account yet, it’s as easy as using Janrain’s Engage Social Sign-in Widget. Visit rpxnow.com to begin the process, or follow the Creating Applications instructions.

Figure 2: The Dashboard Home Page

When you arrive at the Dashboard,

1. On the Quick Links menu at the right, select Sign-In for Websites.
2. You will be presented with the Configure Widget page (see Figure 3). Configure and design the widget here. A preview of how it will appear is presented on the right. For the purposes of this guide, from the Layout menu, under Type select Modal. This will launch the widget in a dialog box when the user clicks on a link.
3. For Basic users, click the Save this configuration on the Engage servers radio button. The Generate the Code button turns to a Save button. Click Save.
   For Pro or Enterprise users, leave the Embed the configuration in the JavaScript code radio button selected. Click the Generate the Codebutton.
   

   Figure 3: Configuring the Widget Page

Once the code is generated, you’ll see a success message (Figure 4).

Figure 4: Success Message

4. Select Get the Code from the top navigation menu.

The Dashboard generates the code needed to add the Social Sign-In widget to a website (see Figure 5). Keep this window open. You will need to make changes on the Call the API screen after the next step.

Figure 5: Get the Code Page

Adding the Widget to a Website ¶

Once the Janrain servers create your widget, you need to

• Choose an authentication method. You will need to create a Token URL page, or similar server page. This is a file on the web server that must hold your apiKey and the One-Time Token that the Janrain servers return to the widget
• Paste the generated JavaScript into the correct places.
• Add your domain to a whitelist in the Dashboard, allowing Janrain to communicate with your newly installed widget.

Create a Token URL ¶

1. Create a file named test_token.php. (Use a text editor to create the PHP file.) For the purposes of this guide, copy the example script located here and paste it in the test_token.php file:  https://github.com/janrain/Janrain-Sample-Code/blob/master/php/rpx-token-url.php
2. In the example script, you need an API key for authorization, that you can find at the bottom of your Dashboard home page. You will need to create a file somewhere on your web server that can be accessed by the HTTP server, but is not publicly available to the Internet. In this file paste in your API key, and save it. Update the string labeled PATH_TO_API_KEY_FILE to contain the absolute path to this file. (See Figure 6.)
3. Move test_token.php to your web server, and place it in a public folder. Make a note of the URL of this file, as you will use it in the next section. (The location of your web server will vary, depending on your system and how you installed it. If you are unsure where your web server is located, on Windows or Macintosh, look for htdocs, or usr/<name>/sites; on Ubuntu, look for var/www.)

Figure 6: API Key Placement

If you want to use client-side authentication, you will create a similar page instead of the Token URL page. See Client-Side Authentication.

Note: The Janrain Dashboard uses time-limited sessions. You may need to sign in again if your session has expired.

Add the Widget to the Existing Codebase ¶

1. The first section of code generated in the Dashboard is called the Widget Initialization Script (seen in Figure 5). Copy this and paste it in the <head> section of your web code.
2. Replace the value for janrain.settings.tokenURL with the URL to the recently created token URL page on the site (or the Client-Side Authentication page, if you used that method). This must be an absolute URL.
3. The second link provided at the bottom is the Widget link. Use this tag to create a hyperlink in the <body> section of your site. When the user clicks this, the modal widget will launch.
4. Save and upload the changes to your web server. (The location of your web severr will vary, depending on your system and how you installed it. If you are unsure where your web server is located: on Windows or Macintosh, look for htdocs, or usr/<name>/sites, on Ubuntu, look for var/www.)

Whitelist your Website ¶

1. Return to the Dashboard, and select Call the API, which is the next step after Get the Code. Finalize your authorization settings here.
2. Enter your domain to the whitelist (see Figure 7). Depending on how your domain is routed, you may need to add an additional entry with the URL prefix:  example.com and www.example.com.
   Note: Do not use any upper case nor invalid characters in the URL.
3. Click Save.

Figure 7: Configure the Whitelist

Now you have integrated the widget.

Test the Widget ¶

Point a browser to your web page and click on the link assigned as the Widget link. If successful, a Social Sign-in page (see Figure 1) will appear on top of the site.

Click through with one of the Identity Providers listed. You will be redirected from the Sign-in Widget to the test_token.php page, which will list all of the information passed from Janrain Engage.

Code Sample: Example Data Output

SERVER VARIABLES:
array(46) {
   ["sERVER_SIGNATURE"]=>
   string(0) ""
   ["UNIQUE_ID"]=>
   string(24) "12345678912345678912345"
   ["HTTP_USER_AGENT"]=>
   string(117) "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_2) AppleWebKit/535.2 (KHTML, like Gecko) Chrome/15.0.874.121 Safari/535.2"
   ["SERVER_PORT"]=>
   string(2) "80"
   ["HTTP_ORIGIN]=>
   string(25) "http://example.rpxnow.com"
   ...

Try returning to the original page and clicking the Widget link again. Because this is a return experience, the widget will provide a streamlined sign-in dialog box (see Figure 8).

Figure 8: Streamlined Return Sign-in

Congratulations! You’ve just integrated Janrain Engage with your website.

Related Topics ¶

Of course, this is a simplified example of Janrain Engage and its Social Sign-in Widget. Janrain Engage allows administrators several ways to customize the social sign-in experience, and also offers an API for developers who want to build their own interface from the ground up.

Administrators will also most likely wish to take full advantage of the profile data returned upon authorization, as well as exploring the other features in Janrain Engage, such as the Social Sharing widget, inviting friends to a website, and more.

Next Steps: ¶

• Social Sign-in Widget – This section is an in depth user guide for the Sign-in Widget, with a focus on the integration process.
• Social Sign-in Javascript API – This section details the the javascript API provided for customization of the widget, and extension of Sign-in features.