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:
- Configure Providers and Permissions
- Design the UI with the Dashboard
- Update Application Settings
Creating a Social Login Application
To create your Social Login application:
- Log in to dashboard.janrain.com.
- Click New Property. The New Property dialog appears.
Figure 1: New Property Dialog
- In the New Property dialog, click Create an App.
- 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.
- 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.
Figure 2: Application Home Page
Your application home page is displayed.
Figure 3: Application Home Page / Social Login Dashboard
1. 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.
- To access the provider configuration page, click the pencil icon ( ) in the Providers section.
- Configure applications for each of the providers that you want to appear as buttons to the end user.
- 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.
- 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.
- 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.
- 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.
- 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.
2. Design the UI with the Dashboard
- 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.
Figure 4: Sign-in Page, Layout Tab
- Configure the layout and style for your UI. Your changes will be reflected live in the preview area.
- Some design options are only available to Pro- or Enterprise-level customers.
- 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.
- 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.
Figure 5: Sign-in Page, Providers Tab
- 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
Note: If you are using Janrain’s Registration solution, always select the Save and Publish option.
Figure 6: Save and Publish Option
3. Get the Code
Figure 7: Get the Code Page
- Copy the widget initialization script and paste it in the
<head> element of the destination web page.
- Copy the widget placeholder or link and paste it in the
<body> element of the destination web page.
- If you designed an embedded UI, this is a
<div> element. Copy it to the place you want the UI to appear.
- 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.
4. 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:
- 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.
- 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.
5. Update Application Settings
Figure 8: 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)
Figure 9: Domain Whitelist
For security reasons, only whitelisted domains are allowed to communicate with your Social Login application.
- Add the token URL to the whitelist.
- 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
Custom URL Shortening (optional)
Figure 10: 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)
Figure 11: Application URLs
These are links to files on your servers.
- 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)
Figure 12: Token URL Redirect Message
Text that will appear in the lower-left side of the Social Login dialog after a user authenticates.
Figure 13: Migrations
Options for making
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.
Figure 14: 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.