Mapping Guide

You must have a Pro or Enterprise level service agreement with Janrain to use this feature.

Account Mapping Integration Guide ¶

Janrain Engage enables websites to associate one of the site’s conventional user accounts with all of the user’s social identities. We call these associations account mappings. This allows the site to provide social sign-in for your existing legacy user accounts without making a database schema change. Your site’s users can be allowed to change Identity Providers without accidentally creating another account on the site.

Account Sign-In Mapping Flow ¶

Figure 1 illustrates the steps in the account sign-in mapping flow as follows:

1. Site Sign-In Start Page

The page on the site where the users opt to sign-in.

2. Janrain Engage Social Sign-In

The dialog or embedded HTML for Sign-In.

3. Authorize Social Identity

The Identity Provider’s authorization dialog.

4. Account Exists?

Site gets auth_info and determines if there is an existing mapping by looking at auth_info or if they are able to auto-map to an existing user by matching their records with the social data provided. If a match is found, a call to the map API call should be made to avoid the need for future auto-map checks on the site. Matched users proceed to step (5.)

4a. Pre-fill Registration Data

Site applies user profile data from the social sign-in to pre-fill some or all of the registration information. Site may choose to skip the display of the registration form (4b.) if they deem the provided data sufficient.

4b. Registration Form

User enters any additional data required to create an account. (Can be skipped if information in (4a.) is deemed sufficient.

4c. Create Account – Site creates account

Site creates a user account and calls the map api call to associate the account with the identity the user used to sign-in.

5. Start Session

Site creates the user’s authenticated session in the way normal for their platform. e.g. php SESSION.

6. Authenticated Experience Landing Page

This can be the same as the start page but with the ability to provide custom content and additional features.

Data Relationship ¶

Figure 2 represents a website using Janrain Engage with a Users table that has a primary key called ‘id.’ A user has bound three different provider identities to their account, and, because the website is using the mapping API, they may use any one of their mapped accounts to sign in as the BrianMan692 user.

Prerequisites

A user record must be created in the site’s database first so you can have the primary key ready to pass into the mapping API. The user must also have verified their identity with Janrain Engage, so the site will have extracted their social identifier via the auth_info API call.

Subsequent Calls

After the mapping is made, when the user signs in with their brian.myopenid.com OpenID for example, an auth_info response, including the primaryKey, will be returned. Use the value of the primaryKey field to sign the user in as BrianMan692.

Best Practices ¶

Sites with a large existing user base who may be familiar with a legacy sign-in system can still benefit from the convenience and enhanced security of the social sign-in flow. It is easier on everyone to have one point of entry for sign-in rather than trying to support two different systems.

We recommend:

• Common entry point and flow for new, existing and legacy users.
• User managed account mapping.

Sign-In Flows ¶

Common Base Sign-In Flow

1. User initiates sign-in and selects a provider.
2. User authenticates at provider site.
3. Site displays their signed-in user experience.

First Time Social Sign-In

There are a few special cases that must be handled. All of them can be detected after the social sign-in is completed. The user may be new to the site, or a legacy user may sign-in in the new way for the first time.

Automatic Legacy Mapping

You may choose to try and use the profile data to map existing users silently if their email addresses match. This makes the migration experience seamless for those users but may present a security risk.

Special Users:

• True first time users
• Legacy users using social sign-in for the first time

User Experience Options:

1. Always show the new user registration, but provide a link to a legacy sign-in.
2. Always show the legacy sign-in, but present a link to the registration form.
3. Show both forms on one page.

You should choose one of these options for your sites based on which is the most common case for each site.

1. Most users are new users
2. Most users are legacy users
3. Equal parts new and legacy

This site design choice should be revisited if these demographics change.

User-managed Mapping and Additional Accounts ¶

Your site may allow users to map additional providers from a user settings page provided by the site. This has benefits for the site and for the user. Sign-in can continue to be seamless if one of their providers is having an outage, as well as allow easier sharing with friends. The site benefits because each provider that the user maps can add user profile data, as each provider supplies a different view of the user.

Interface ¶

In the user’s settings page the site should display a list of mapped providers, each with an option to remove the mapping, and, next to the list, an Add Provider button to add an additional provider. The Add Provider button launches a similar experience to sign-in except it returns the user back to the settings page.

Alternate Token URL ¶

The easiest way to handle the Add Provider button and redirect the user back to the settings page is to create an alternate Token URL on your server and pass that path to Janrain Engage’s token_url parameter.

This Add Provider – Token URL should perform a less-complicated version of the sign-in Token URL handler.

You probably already keep the primary key you use to identify a user handy for other operations; you will need it here.

What the alternate Token URL should do:

1. Extract the provider profile data from auth_info.
2. Call the Engage Mapping API call map method, passing the primary key (See data relationship diagram above) and the identifier from the provider; this is the same as you do when mapping during sign-in.
3. Redisplay the user settings page with the list of mapped providers.

Wording ¶

Try to find the wording that describes these items that is the closest match to the majority of your user’s experiences. For instance, we use the technical term Identity Provider where the user might think of them as Social Network or Email Account or simply Account. We use the technical term map while the user might think of it as linking. Your in-line help can mention relevent examples of social networks that will be most familiar to your users.

Create a Flow Diagram ¶

Each sign-in flow can be unique. We’ve shown you our best practice case; your needs may be different.

To understand your own sign-in process, we recommend creating a flow diagram similar to the one we have provided here. This will help you understand the peculiarities of your process, help you discuss it with others, as well as allow you to create the opportunity to simplify and stream line before writing a lot of code.

Getting Help ¶

We have experts in user experience design and technical solutions engineers that can help you with your initial design process. We also have a professional services group that can augment your team, so they can concentrate on your core competency.

Get Going ¶

In many cases, even these advanced integrations can be coded quickly and easily by any engineering team. Reviewing the design presented here and tweaking it to fit your users is the important part of the work.