Advanced Customization

Contents

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.

Customize Your Application Domain

Available to: Pro Enterprise

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

domain-displayed-during-social-authentication-1

Figure 1: 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, login.customer.com). 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:

Add the following line to your JavaScript script:

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:

Here is an example of implementing third-party analytics.

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.

Scopes-Example

Figure 2: 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:

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 this topic for more information on Social Login settings.

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.

Implementation

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 this topic for more information on Social Login settings.

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

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:

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:

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:

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.