Customizing Social Login

Retrieve User Data

The object returned by the auth_info call can contain a number of object fields, and these will vary depending on several factors, including identity provider and service level. You can use that information to greet the user by name, display the user’s photo from an identity provider (for example, their Twitter photo), send an email to the user using his/her verified email address, and so on.

One profile object that is always included is 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. For example, if you want to store user information that you gather above and beyond the social login process in a database, you might want to use identifier as the unique ID for users.

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 by Provider.

Customize Your Application Domain

Available to: Pro Enterprise

By default, Social Login applications are created on the Janrain domain (for example, This domain may be displayed briefly to users during the social authentication process.

Domain Displayed during Social Authentication

For production Social Login applications, Janrain can configure the domain to use a custom subdomain that you host (for example, Janrain will work with you to set this up using the following process. The subdomain must not be used for any other purpose, and you must be able to modify your DNS.

  1. Customer chooses a subdomain and sends it to Janrain.
  2. Janrain sends back the Janrain endpoint for the CNAME entry.
  3. Customer uses this endpoint to set a CNAME entry in their DNS.
  4. Janrain completes setup and procures an SSL certificate.
  5. Janrain provisions the production application with the custom subdomain.

Customize the Appearance of The Social Login UI

Available to: Pro Enterprise

After adding the Social Login code you obtained from the Janrain Dashboard, your document will look something like this:

(function() {
    if (typeof window.janrain !== 'object') window.janrain = {};
    if (typeof window.janrain.settings !== 'object') window.janrain.settings = {};

    janrain.settings.tokenUrl = '';

    function isReady() { janrain.ready = true; };
    if (document.addEventListener) {
      document.addEventListener("DOMContentLoaded", isReady, false);
    } else {
      window.attachEvent('onload', isReady);

    var e = document.createElement('script');
    e.type = 'text/javascript'; = 'janrainAuthWidget';

    if (document.location.protocol === 'https:') {
      e.src = '';
    } else {
      e.src = '';

    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(e, s);

Add the following line to your JavaScript file:

janrain.settings.custom = true;

Now you’ll be able to build your own Social Login experience using our JavaScript API.

Implement Third-party Analytics

One of the features available in the Janrain Social Login JavaScript API is the ability to send data to popular third-party analytics sites, such as Google Analytics and Adobe SiteCatalyst. An administrator can use these analytical tools to gain greater insight into how users interact with the website.

The JavaScript API fires events that you can track and report as needed. The API provides fine-grained data based on user actions. Some common events you might wish to track are:

  • onProviderLoginStart — Marks the successful initiation of a login.
  • onProviderLoginComplete — Marks the successful or unsuccessful completion of a login.
  • onProviderLoginSuccess — Marks the successful completion of a login.

Here is an example of implementing third-party analytics.

Note: If you want to implement third-party analytics for Registration, please see our documentation on Customizing Registration, as it utilizes a different JavaScript API.

Assign Scopes on a per-page Basis

When a user takes advantage of social login, the user is asked for permission to use data from his/her profile, such as email address and name. The process of choosing which information is requested is called setting a scope.

Asking Scope Permission

By default, the scopes for a Social Login application are the same across all web pages using the same application. However, these scopes may be set on a per-page basis as well. To tailor the social login scopes to individual sites, there are two alternate best practices:

  • Create a separate Social Login application for each site and manage the permissions requested for each application in the Janrain Dashboard. This is ideal for cases where total control and complex analytics are needed.
  • Implement a single Social Login solution and use the Override Scopes feature to manage the permissions requested on a per-page basis. This feature must be enabled for you by your Janrain representative.

Override Scopes

To implement scope overriding on sites utilizing the same Social Login application, add the scopes JavaScript setting for each page returning custom information to the login script. See Social Login JavaScript API for more information.

janrain.settings.scopes = {"googleplus": [""]};

When present, the scopes setting will override the scopes set for the Social Login application in the Janrain Dashboard. All provider-required scopes will still be present. If no scopes setting is on a page using the Social Login application, the default scopes set in the Dashboard will be used.

Progressive Permissioning for Facebook

Available to: Pro Enterprise

Progressive permissioning is a means of requesting additional permissions from the user, gradually and based on the user’s activity on the site. In a progressive permissioning strategy, when a new user signs in, the site requests minimal permissions. Later, when the user wants to complete an action such as posting a comment or sharing a video, the site requests further permissions.

The challenge of progressive permissioning is learning what your user base is comfortable with and how different permission requests affect conversion rates. We recommend preparing a series of A/B tests and tracking the respective performance of different request buckets.


Progressive permissioning for Facebook is enabled with the facebookPermissions setting, which must be set as an array. For other providers, see Assign Scopes on a per-page Basis. See Social Login JavaScript API for more information on scopes.

To implement progressive permissioning requesting access only to a user’s email address, modify the facebookPermissions property as follows:

janrain.settings.facebookPermissions = ['email'];

Or, if you want to request access to the user’s email address, location, and Likes, as well as to post to the user’s Timeline, set the facebookPermissions property to an array with the following values:

janrain.settings.facebookPermissions = ['email', 'user_location', 'user_likes', 'publish_stream'];

To see which values can currently be included in this array, check the Facebook developer’s page. Facebook adds new values often, so be sure to check frequently. Currently, when a user logs in to your application and no additional permissions are requested, the following properties are available to all applications by default:

  • age_range
  • first_name
  • gender
  • id
  • last_name
  • link
  • locale
  • name
  • username

Here is an example of implementing progressive permissioning with Facebook.

Log Users Out of Facebook

You may want to log your users out of Facebook at the same time a Social Login session ends. The best practice for achieving this is to use the Social Login event system combined with the janrain.engage.signin.logoutFacebook method to log the user out of both systems. See the Janrain-Sample-Code repo for an example of this in action.

Add a Custom Provider Button

Available to: Pro Enterprise

For more authentication options on your site, you may add OpenID providers to the Social Login UI. Find out more about becoming an OpenID Provider here.

To add a custom provider button, configure the following settings:

Field Description
customOpenid Set customOpenid to true to use the custom OpenID settings.
customOpenidFlow Use this to set the flow. Enter the name of a valid flow file (for example: openid).
customOpenIdProviderName Optional
Use this to create the button text (usually, the Identity Provider name).
The default text is “Sign In”.
Note: Long provider names will be truncated. Also, a leading symbol is needed when adding an apostrophe to text (for example: Provider’s).
customOpenIdProviderColor Use this setting to define the color of the button text. Use a standard webcolor hexadecimal value (for example: #729fcf).
customOpenidProviderId An ID that you create to use for keying configuration objects in the multi-custom OpenID scenario, or to call the trigger flow. For example: yourCustomId.
customOpenidIdentifier This URL must point to a valid OpenID endpoint.
customOpenidOpxblob Use this setting to pass information to the provider as JSON.
customOpenidLargeIcon Enter the full path to a large icon image for the provider. Other Janrain provider icons are 128×128 pixels. This image must be hosted on your servers.
providers Add the custom provider ID created in the customOpenidProviderId setting to the array of available identity providers in your UI. You must also add openid to this array.

Single Custom OpenID Setup

To enable a single OpenID provider in your UI, your code should look similar to this:

janrain.settings.providers = ['google','facebook', 'openid', 'open-eye-dee'];
janrain.settings.customOpenid = true;
janrain.settings.customOpenidFlow = 'openid';
janrain.settings.customOpenIdProviderName = 'yourCustomId';
janrain.settings.customOpenIdProviderColor = '#729fcf';
janrain.settings.customOpenidProviderId = 'open-eye-dee';
janrain.settings.customOpenidIdentifier = '';
janrain.settings.customOpenidOpxblob = '{'origin':'','otherParam':'other cool value'}';
janrain.settings.customOpenidLargeIcon = '';

Multi-custom OpenID Setup

To set up multiple OpenID providers in your UI, use code similar to this:

Note: The icons will not display properly unless you modify the CSS for your UI.

janrain.settings.providers = ['google','facebook', 'openid', 'alpha', 'gamma', 'beta', 'delta'];
janrain.settings.customOpenid = true;
janrain.settings.customOpenidProviderId = ['alpha', 'gamma', 'beta', 'delta'];
janrain.settings.customOpenIdProviderName = {
    'alpha': 'Aardvark',
    'beta': 'Badger',
    'gamma': 'Giraffe',
    'delta': 'Donkey'
janrain.settings.customOpenIdProviderColor = {
    'alpha': '#729fcf',
    'beta': '#729fcf',
    'gamma': '#729fcf',
    'delta': '#729fcf'
janrain.settings.customOpenidIdentifier = {
    'alpha': '',
    'beta': '',
    'gamma': '',
    'delta': ''
janrain.settings.customOpenidLargeIcon = {
    'alpha': '',
    'beta': '',
    'gamma': '',
    'delta': ''

Account Mapping

Janrain Social Login enables your site to associate a conventional user account with all of a user’s social identities. We call these associations account mappings.

The /map endpoint will store a primary key for a user from your database with each of the user’s external social identifiers on the Janrain server. In order to use the mapping API, a user record must exist in your database, and the user must have verified his/her identity with Social Login so that you have both the primary key and the social identifier. All of a user’s account mappings, including the primary key, will be returned on every subsequent call to auth_info.

The following diagram represents a website using Social Login with a Users table that has a primary key called id. A user has bound three different provider identities to the user’s account, and because the website is using the mapping API, the user may use any one of the user’s mapped accounts to sign in as the BrianMan692 user.

User Mappings on Social Login server

Account Mapping in the Login Workflow

When a user authenticates through Social Login, your site can evaluate the auth_info response to determine the appropriate next step in the login workflow:

  • If an existing account mapping is found, log the user in to your site (as you would normally do).
  • If an existing account mapping is not found, but the social data returned includes a verified email address that matches one of your existing users, use the /map API call to associate the user’s primary key with the social identifier used for authentication and log the user in to your site.
  • If an existing account mapping is not found, and you cannot identify an existing user based on the verified email address returned, proceed with your site’s registration process and map the new primary key created with the social identifier used for authentication after registration is complete.

User-managed Account Mapping

Your site may allow users to map additional providers to their account from an account management page. This page should display a list of users’ mapped providers, each with an option to remove the mapping, along with links to add additional providers for authentication.

The easiest way to handle the additional provider buttons and redirect the user back to the account management page is to create an alternate token URL page and pass that path to the Social Login token_url parameter with the auth_info call. This alternate token URL should:

  1. Extract the provider profile data from auth_info.
  2. Call the /map endpoint, passing the user’s primary key and the new social identifier.
  3. Redisplay the user back to the account management page with the list of mapped providers.
Scroll ↓