
Account Linking with Facebook
On this page
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, and requires a version of 7.5 or later. An HTML Authenticator will be used as a local authenticator, 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
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.Under Account Manager That Holds the Links, choose
default-account-manager
and for Account Domain on Link choosefacebook-domain
In the Advanced section, under Original Subject Attribute Name, add
linked_subject
.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.
After the previously created
check-link
action, click Add to add a second Action on the Facebook Authenticator.Choose New Action, give it a name (check-if-link-exist) and choose the type Switch
Name the If statement (no-link) and add a condition to check if the link was not available,
attributes.subject.linked_subject == null
In the else row, select
Succeed if no conditions match
from the drop-down
In the Execute column, click Create
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
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. Ensure that the option forDisable Second Factor Subject Check
is selected. This action 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.
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.Click the green checkbox and then Close
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 NextIn the drop-down for Linking Account Domain, choose
local-domain
. Under Main Account, selectIn Link Account Domain
and for Store In choose thedefault-account-manager
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
, clickNext
Under Account Manager That Holds the Links, choose
default-account-manager
and for Account Domain on Link choosefacebook-domain
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):
account_id | linked_account_id | linked_account_domain_name | linking_account_manager | created |
---|---|---|---|---|
855326...2db3ac | 101571...31682 | facebook-domain | default-account-manager | 2020-08-17 21:00:18 |
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.