Social Login Overview

Janrain’s Social Login offering supports convenient and secure sign-in, authenticated by a long and growing list of identity providers including:

  • AOL
  • Facebook
  • Google+
  • LinkedIn
  • PayPal
  • Twitter
  • Yahoo!

Once a user has signed in, your application can use Janrain’s RESTful API to access user profile data.

Social Login authenticates a user and returns social data. It is up to your application to determine a user’s logged-in state, as well as store the returned data.

For a solution that includes storing the user data, see the Registration Overview.

Social Login Flow Walkthrough

The following diagram shows how a user signs in to your website using Janrain Social Login. For more information on Social Login configuration options, see Implementing Social Login.

Social Login Flow
  1. User clicks login and chooses a social provider through which to authenticate. The Social Login widget supports both modal and embedded presentation modes.
  2. User logs in on the selected identity provider’s site (for example, Facebook, Google+, Twitter, and so on) and approves the use of your application with their account. The Social Login widget supports both popup window and redirect-based login flows.
  3. The social provider communicates with the Janrain servers and securely provides authentication and identity information. The type and amount of data provided depend on the provider being used. For more information, see User Profile Data by Provider.
  4. Janrain posts an access token to your token URL.
  5. Using the access token and your API key, your application can fetch data about the user through our Social Login REST API.
  6. User data can be served to your site to customize the end-user experience.

Social Login Dashboard

The Janrain Dashboard provides a central location from which to administer the features of Social Login. Each Social Login application listed as a property on the Dashboard home page has its own unique configuration page, similar to the one shown here.

Social Login Dashboard

This page consists of the following sections, which provide high-level information about the application and access to more detailed information as well as the application configuration UI.

  • Analytics — Shows 30-day averages and trend graphs for the application. Click any of the categories or the arrow at the top right of the Analytics box to display a detailed view of the corresponding data. For more information, see Social Login Analytics.
  • Providers — Lists the identity providers configured for the application and shows the percentage of users who signed in with each provider. When you hover over a provider, click the wrench icon to configure the provider settings. See the Provider Setup Guides for specific setup instructions.
  • Settings — Provides access to the Application Settings page, where you can set up your domain whitelist, access your application domain and API credentials, and manage other aspects of your Social Login application.
  • Widgets and SDKs — Provides links to the configuration UI for Social Login and Social Sharing and resources for using the Social Login iOS and Android SDKs. For information on configuring through this UI, see Design the UI with the Dashboard.
  • People — Lists the administrators in your organization who have access to the application. Click the pencil icon at the top right of the card to send invitations (valid for three days) to additional email addresses or remove people who currently have access.

Implementing Social Login

A Social Login application is needed for implementing both social login and social sharing.

Note: If you are using Janrain’s Registration solution, Social Login is included as part of the Janrain deployment process. The only instructions that you need to follow in this section are:

Creating a Social Login Application

To create your Social Login application:

  1. Log in to dashboard.janrain.com.
  2. Click New Property. The New Property dialog appears.
    New Property Dialog
  3. In the New Property dialog, click Create an App.
  4. Choose an Application Name and click Create Application. At the Basic service level, your name will be appended to the rpxnow domain, appearing as yourdomain.rpxnow.com. You can customize this URL at higher service levels.
  5. The Janrain servers generate the application you have created. Once you click Get Started, your application is ready to use.

If you are implementing Social Login on multiple sites, you can use the same application across all sites, or you can create different applications for each one. If you would like the provider login and permissions screens to be individually branded for each of your sites, then you will want to create additional Social Login applications (following the previous steps).

Configuring a Social Login Application

Once you have created an application, click the app’s Manage Engage App button to configure it.

Application Home Page

Your application home page is displayed.

Application Home Page / Social Login Dashboard

Configure Providers and Permissions

The first step in deploying Social Login is to select which identity providers will be offered to users and configure the permissions requested from users.

  1. To access the provider configuration page, click the pencil icon ( pencil icon ) in the Providers section.
  2. Configure applications for each of the providers that you want to appear as buttons to the end user.
    1. Not all providers require configuration. A gray gear icon indicates when configuration is required, and the dashboard will automatically prompt you to complete configuration if you attempt to enable a provider that requires it. Once a provider has been set up with all required fields, the gear icon will turn green.
    2. See the Provider Setup Guides for specific provider configuration instructions. Note that providers regularly change or update their developer tools. We try to keep directions as up-to-date as possible, but some steps may differ slightly from the currently-documented process.
    3. Note that if you have both a development and a production Social Login application, you need to follow these provider configuration steps individually for each application.
  3. Set which permissions you want to request from users when they sign in with a particular social provider. Select features to prompt users for permission to that part of their profile when they authenticate. Features that are not selected are returned automatically.
  4. Facebook applications must pass a Facebook login review before features marked in the Dashboard with an asterisk (*) will be returned. For more information about the audit process, see Facebook’s login review page.

Design the UI with the Dashboard

The Janrain Dashboard provides a UI designer with live preview. For those who need more customization, the JavaScript API can augment the UI created in the Dashboard, or the UI can be coded from scratch.

  1. In the Widgets and SDKs section, click Sign-ins to access the Configure Widget page. A preview of how the UI will appear is presented on the right.

    Sign-in Page, Layout Tab / Social Login Dashboard

  2. Configure the layout and style for your UI. Your changes will be reflected live in the preview area.

    1. Some design options are only available to Pro-level or Enterprise-level customers.
    2. If you are using Janrain’s Registration solution, the modal/embedded option will not affect the modality of the Social Login widget in the signin screen, as this is controlled in a Registration configuration file.
  3. To add configured providers (or providers that do not require configuration) to the UI, click the Providers list and drag providers into the preview area. To delete a provider button in the preview area, click the Close icon in the button’s upper-right corner.

    Sign-in Page, Providers Tab

  4. Once you have completed configuration, click Save to save your configuration to the Janrain servers. This allows for a single, central configuration located on the Janrain servers. Changes made on the Dashboard automatically propagate to deployed integrations on client websites. Changes are usually implemented immediately, but may take up to an hour to propagate.

For Pro and Enterprise Service Levels

Pro- or Enterprise-level customers may select either the Save and Publish or Save and Embed options for saving configurations. Configuration settings are included in the JavaScript code that is generated for integration into your site (available on the Get the Code page). The Save and Embed option allows you to modify configurations independently of the Dashboard, which is useful for maintaining multiple UI instances with different configurations.

Note: If you are using Janrain’s Registration solution, always select the Save and Publish option.

Save and Publish Option

Get the Code

Get the Code Page

Once you have saved your configuration, the JavaScript code is available from the Dashboard’s Get the Code page. This code must be placed on all pages where the UI will appear. If you are using Janrain’s Registration solution, do not complete this or the next section.

  1. Copy the widget initialization script and paste it in the <head> element of the destination web page.
  2. Replace the placeholder in the JavaScript code with your token URL (see step 3 for more information).
  3. Copy the widget placeholder or link and paste it in the <body> element of the destination web page.
    1. If you designed an embedded UI, this is a <div> element. Copy it to the place you want the UI to appear.
    2. If you designed a modal UI, this is the <a> element that the user clicks to make the UI appear. Copy it to the place you want the link to appear.

Create a Server-side Token URL

The token URL is a page hosted on your site that receives a token posted by Janrain after a successful social login and retrieves user profile information. You can build the token URL page with any number of web technologies, as long as it can perform these basic steps:

  1. Accept the one-time token — Janrain POSTs a one-time token for the session to the token URL. Store this token for the auth_info call, or other API calls to the Janrain servers.
  2. Request profile information — Using your API key (found in the Dashboard), and the one-time token, use the auth_info call to request profile data from Janrain.

By default, a successful social authentication will redirect the user to the token URL page to make the auth_info call and then initiate a page refresh for the site to receive the user information. You can also configure the login process to proceed without a page refresh by listening for the Social Login event for onProviderLoginToken and posting the one-time token to your token URL with an AJAX call.

See the Janrain-Sample-Code GitHub repo for some example token URLs.

Update Application Settings

Settings Section

The final step in deploying Social Login is completing the Application Settings page. To access this page, click the pencil (Manage Settings) icon at the top right of the Settings section on your home page. The Application Settings page includes information on your:

  • service plan
  • application domain and ID
  • API key

Warning: Your API key should always be kept secret. Never email the key or include it in a support ticket!

Domain Whitelist (required)

Domain Whitelist

For security reasons, only whitelisted domains are allowed to communicate with your Social Login application.

  1. Add the token URL to the whitelist.
  2. Add the domain(s) and subdomain(s) of any sites where you plan to implement Social Login to the whitelist. Depending on how your domain is routed, you may need to add an additional entry with the URL prefixes example.com and www.example.com.

Custom URL Shortening (optional)

Custom URL Shortening

If you are implementing social sharing, you can customize the domain used for shared links if you have a URL shortening service.

Application URLs (optional)

Application URLs

These are links to files on your servers.

  • Privacy Policy URL — Link that may be displayed on social provider permissions screens.
  • Favicon URL — Image that may be displayed on social provider permissions screens.
  • Domain Redirect — A URL that users are sent to if they type your Social Login application domain directly into a browser.

Token URL Redirect Message (optional)

Token URL Redirect Message

Text that will appear in the lower-left side of the Social Login dialog after a user authenticates.

Migrations (optional)

Migrations

Options for making auth_info calls.

You can now use the Social Login functionality.

Testing Social Login

The Dashboard includes a testing tool, accessible in two ways:

  • On the Configure Widget page, click the Launch a test widget link at the top of the screen. (This link appears when you save configuration changes.)
  • On the Call the API page, click the Launch a test widget link on the right side of the screen.
Test Sign-in Widget

The testing tool implements the application as you configured it, allowing you to simulate a login and retrieve the user profile from the selected identity provider. After you retrieve the profile, you can fill in the token URL and test your own code for retrieving the user profile.

Single Sign-on with Social Login

Overview

Janrain’s Single Sign-on (SSO) functionality enables your customers to register or log in once and effortlessly navigate across your multiple websites without needing to log in again. SSO is also available for Registration.

By default, Single Sign-on authenticates all users who visit a member site who have an active SSO session open. Using segments, you can implement a more fine-grained SSO experience on your sites. If no segment setting is present, all users with an SSO session are automatically signed in to all customer sites.

For example, a large music brand can segment by artist and associated online stores. This lets a user log into a band’s site and SSO automatically signs the user into an online store in the same segment, but not into another artist’s site.

Multiple segments may be supported on a site. For example, a holding company with many brands may segment SSO by each brand and also allow users who have logged in on any brand’s site to be automatically logged in on the primary holding company site.

Segment settings are stored locally, and end users may manipulate their segment identifiers, so this feature should not be used for site security or restricting access.

Configuration Information Needed

You will need the following configuration information to implement SSO with Social Login:

Configuration Parameters Provided By Description
sso_server Janrain The URL to the Janrain Single Sign-on server.
token_uri Customer The callback URL on your site that will receive the authentication token.
xd_reciever Customer A static page on your site used to securely pass the authentication token to the token_uri.
logout_uri Customer A page on your site that logs the user out of all SSO-enabled sites. If you do not have a logout_uri, you must set this to null.
segment Customer Optional — The name of the segment to which the site belongs. Sites on the same domain must use the same segment. The name may only include alphanumeric characters, with no spaces, slashes, or other special characters.
supported_segment Customer Optional — A comma-separated list of segments that the site allows SSO from in addition to the defined segment.

Implementation Steps

Set Up token_uri

After a user signs in (or is automatically signed in through SSO), Janrain sends a token to a callback on your website. This is known as the token_uri, which you will have set up for your Social Login implementation. This code sample shows how to set up a token_uri.

Set Up xd_reciever URLs

Each site needs to host a static XD receiver (cross-domain receiver) page, which is used to securely pass the token to the token_uri through JavaScript. The page is never visible to the end user. The XD receiver page for each site should reside on the same domain as the main site, or Single Sign-on may not work in some browsers.

The following code must be included on the XD receiver page:

<html>
  <script src="https://d1v9u0bgi1uimx.cloudfront.net/static/xd_receiver.js" type="text/javascript"></script>
</html>

Enable Single Sign-on

Once a user has logged in to one of your sites, Janrain will automatically log that user into any other SSO-enabled site that he or she visits. Place the scripts below in the <head> section of each page on your sites to configure SSO (substituting the appropriate URLs as described in the previous table).

<script src="https://d1v9u0bgi1uimx.cloudfront.net/sso.js" type="text/javascript"></script>
<!--Do not modify the above URL-->
<script>
JANRAIN.SSO.ENGAGE.check_login ({
  sso_server: 'https://example.janrainsso.com',
  token_uri: 'https://mysite.com/tokenUrl.php',
  xd_receiver: 'https://mysite.com/xd_receiver.html',
  // If no Logout URL is required for the site, set logout_uri to null
  logout_uri: 'https://mysite.com/logout.php',
  // If you are not using segments, remove the following two lines.
  segment: 'segment_1',
  supported_segment: 'segment_2, segment_3'
 });
</script>

(Optional) Enable Single Sign-Off

Single Sign-on also provides Single Sign-Off functionality, ensuring that when a user logs out of one site, he or she is also logged out of all SSO-enabled sites. The configured logout_uri for each SSO-enabled site that the user visited will be loaded invisibly to run the Single Sign-Off logout function.

The following example shows how to create a Logout link that triggers automatic logout across all SSO-enabled sites.

<script>
  function my_logout() {
    JANRAIN.SSO.ENGAGE.logout({
      sso_server: 'https://example.janrainsso.com',
      logout_uri: 'https://mysite.com/logout.php'
    });
  };
</script>
<button onclick="my_logout()">Sign Out</button>

This logout function will redirect to the page you provide in the logout_uri parameter once it completes. Any site-specific logout logic should be placed in your logout_uri page. Placing any code after the Single Sign-Off logout script may introduce a race condition.