Account linking with Facebook

Account linking is a way of linking or binding a foreign account with a local account. A good example of this concept is linking a social account (foreign account) such as Facebook, LinkedIn, Instagram or Twitter to a local account that is stored in a corporate repository such as a database or directory.

Other uses of account linking that are not explicitly covered by this article:

• Linking legacy accounts with new accounts in an organization merger
• Linking multiple cloud-based accounts with a local account
• Linking multiple social accounts to simplify authentication

This article will cover how to set up account linking in the Curity Identity Server using an HTML Authenticator as the local authenticator that is able to capture the locally held identity that is going to be linked with a Facebook account. The flow will even be able to capture registration of the local account as needed but in a realistic scenario the local account already exists.

Prerequisites

An installation of the Curity Identity Server is needed. If you do not have an installation of the Curity Identity Server, follow this tutorial Installation of the Curity Identity Server and configure the installation by running the Curity Basic Setup Wizard as outlined in this tutorial Curity Basic Setup Wizard.

Account Manager

Account linking is handled by a linking account manager. This is an Account Manager that is configured to use the data source that holds the local account in the link. The Curity Identity Server will have a default Account Manager that is using the default Data Source (HSQL) when the Basic Configuration wizard has been completed. These will suffice for getting an example of linking up and running.

In our example the HTML Form Authenticator will have the capability to register accounts. Since the HTML Authenticator uses the default-account-manager the accounts created as part of the login process will be stored in the Data Source used by this Account Manager.

Account Domains

Linking leverages Account Domains when mapping an Authenticator to being local or foreign. An Authenticator is assigned to an Account Domain. In the linking process, one of the keys that is used to look up a link is the Account Domain. By placing an Authenticator in a domain and making the link key composed of this tuple (domain + authenticator), subsequent links performed with a different authentiator, where the username happens to be the same, can be clearly differentiated.

Create two Account Domains, one named local-domain and the other named facebook-domain.

HTML Authenticator

Creating an HTML Form Authenticator is very similar to creating a Username Authenticator. Configure the HTML Form Authenticator to use the Account Manager (default-account-manager) and the Credential Manager (default-credential-manager).

Go to Advanced -> Account Domains and select local-domain.

In our example this authenticator will be considered the local authenticator as it is mapped to a Data Source that is under our control (the local HSQL database).

Facebook Authenticator

The details needed to create and configure this Authenticator will partially come from settings made in the Facebook Developer account. Follow the Facebook documentation to set that up.

The Client ID and Client Secret are two parameters that needs to be obtained from the Facebook Developer Portal.

Make sure to assign the Authenticator to an Account Domain. Go to Advanced -> Account Domains and select facebook-domain.

Configuring the flow of actions

The flow of resolving a link if it already exists or alternatively establishing the link if it isn't already established.

Action to check if link exist

1. Under Actions and Login, click Add and choose New Action. Give it a name (check-link) and choose the type Resolve Linked Account, then click Next.

2. Under Account Manager That Holds the Links, choose default-account-manager and for Account Domain on Link choose facebook-domain

3. In the Advanced section, under Original Subject Attribute Name, add linked_subject.

4. Click Close

Switch action for alternative flows

The next step is to configure a Switch action that will invoke different actions depending on if the preceeding check-link action was able to resolve a link of not. If a link was resolved use it and if not, the link needs to be established.

1. After the previously created check-link action, click Add to add a second Action on the Facebook Authenticator.

2. Choose New Action, give it a name (check-if-link-exist) and choose the type Switch

3. Name the If statement (no-link) and add a condition to check if the link was not available, attributes.subject.linked_subject == null

4. In the else row, select Succeed if no conditions match from the drop-down

5. In the Execute column, click Create

6. The action invoked if there is no link will be a sequence of actions. Give it a name (create-link) and choose the type Sequence, click Next

7. Click Add to add the first action in our sequence. Choose New Action, give it a name (html-authenticator) and choose the type Multi Factor Condition, click Next. This will cause the HTML Authenticator to be triggered. If the user already has a local account an authentication here will capture that identity and later use that for the linking. If the user doesn't have a local account, the HTML Authenticator can be used to create the account.

8. Under Condition choose subject-condition, click Add to add a pattern. We want this to apply to any pattern, under Subject Pattern type .* and click Select authenticator, choose the previously created HTML Authenticator.

9. Click the green checkbox and then Close

10. Click Add to add the second action in our sequence. Choose New Action, give it a name (link) and choose the type Auto Link Account, click Next

11. In the drop-down for Linking Account Domain, choose local-domain. Under Main Account, select In Link Account Domain and for Store In choose the default-account-manager

12. Since the action to first resolve a link did not find a link we ended up in a branch of the flow that creates the link. Now that the link is created it needs to be resolved. Click Add to add the third action in our sequence. Give it a name (resolve-link), choose type Resolve Linked Account, click Next

13. Under Account Manager That Holds the Links, choose default-account-manager and for Account Domain on Link choose facebook-domain

14. In the Advanced section, enable Fail on No Link, click Close. It should not really be possible that no link exists here since the preceeding action creates the link. This is just a failsafe.

The sequence action is now ready and looks like this:

The Facebook Authenticator should now look like this:

Assign to a Client

The Facebook Authenticator can now be assigned to a Client. As an example, a client using the Code Flow would be good to test our scenario. Note that only the Facebook Authenticator needs to be assigned, the HTML Authenticator doesn't have to be explicitly assigned as it is referenced in one of the flows configured on the Facebook Authenticator and will thus be implicitly available.

Configure Facebook

In the Facebook configuration a valid OAuth Redirect URI needs to be added. this depends on what the ID of the Facebook Authenticator is. An example URI where the Authenticator is named facebook is: https://idsvr.example.com/authn/authentication/facebook/callback

Test using OAuth.tools

We can now use OAuth.tools to test our configuration. Above we mentioned the Code Flow as an option for this scenario. In oauth.tools we can initiate a Code Flow.

Since we have the Facebook Authenticator configured for our client we will get a Facebook login screen (if there isn't already a logged in session). Since there probably isn't a link established the next screen would be the HTML Authenticator where we could either log in using our existing account or create a new account.

The first thing prompted should be the HTML Authenticator. Here we can choose to Create account.

When the Account Creation steps are completed we are redirected back to the login screen and can authenticate with the account we just created.

Now the create link and resolve link actions will be invoked but these run in the background and will not be visible. An entry in the Curity database will be added to store the link. It looks something like this (truncated for readability):

Adding the Debug Authentication Action here could help showcase that the subject in this case actually is the subject of the local authenticator, i.e. the HTML Form Authenticator.

Adding the Debug Action would result in the Facebook Authenticator having and additional action in the chain.

When running the flow in OAuth.tools after adding the Debug Action we see that the subject is not for the Facebook Authenticator. The local account in our example is stored in the local database and is alice. However other attributes available such as Name and Email are actually from the Facebook Authenticator, including the id.

Summary

Authentication Actions are extremely powerful in creating advanced workflows in the authentication process. Account linking can help create a very smooth experience for the end user with some simple configurations on the server side. A link is created between accounts in order to resolve attributes from one account using information from another as keys. There are several different ways to achieve account linking and in the end the configuration depends on how the users flow through the system. Some of the configurations could be handled by application code but in this example we were able to achieve the setup for our scenario using only configuration in the Curity Identity Server.

The product documentation describing Account Linking is good resources with details on the basic concepts as well as a few more examples of linking.