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 theBrianMan692 user.
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:
- Extract the provider profile data from auth_info.
- Call the /map endpoint, passing the user’s primary key and the new social identifier.
- Redisplay the user back to the account management page with the list of mapped providers.