Adding social login to your website makes your users’ first visit streamlined and easy, but what about their second visit? Often times, users forget which method they used to log in, and in confusion, accidentally create a second account.

This is why we’re excited to announce the launch of our account linking feature in Stormpath! Account linking allows you to unify your user accounts, allowing them to login to the same account via multiple methods without much development effort.

Using Account Linking

With account linking, each account now has an accountLinks collection, which you (as the developer) may modify programmatically via our REST API. We’ll take a look at how to add links between accounts, and utilize Stormpath to automatically link related accounts.

After logging into an account, Stormpath usually returns data associated with the authenticated account. When you enable account linking, Stormpath additionally searches through the account’s links. If there’s a linked account in the application’s default directory, it’ll return that account instead.

To get started with Account Linking, open up the Stormpath Admin Console and navigate to your application’s policies tab.

Stormpath Account Linking Policy Tab

You’ll see three new options under “Account Linking Policy”: status, automatic provisioning, and matching property.

To demonstrate Stormpath’s account linking feature, I’ll start out with an application without account linking, and with two accounts I have in my directories:

  1. ed /at/ edjiang.com (my personal Google Account), and
  2. edward /at/ stormpath.com (my work email, that I’m using with an email/password).

I’ll spin up the express-stormpath-sample-project, login with my email/password account, and edit my profile, changing the “favorite color” field and saving it into the account’s customData.

Stormpath Sample Project CustomData

If I log in to my application with my Google Account instead, the “favorite color” field will be blank. They’re separate accounts, so the customData stored in each account is completely separate.

Turn On Account Linking

Let’s turn on account linking by changing the status setting to ENABLED.

Stormpath Account Linking Enabled Policy

Now, I’ll link them using the Stormpath REST API (you can also do this via the web interface):

If I now log in with my Google Account, Stormpath finds the account link and returns the email/password account instead (since it’s in my application’s default directory). Going to view my profile, I’ll see that my “favorite color” is set, even though I logged in with my Google Account this time!

Automatic Account Linking

While enabling account linking allows you to have control over when and where accounts are linked, you can also ask Stormpath to automatically link accounts for you, with the automaticProvisioning and matchingProperty settings. For most new consumer applications built with Stormpath, we recommend enabling account linking and automaticProvisioning.

Account Linking Enabled

Automatic provisioning will automatically create accounts in the default directory for accounts in other directories, if not already there. With automatic provisioning enabled, a new login via Google, Facebook, Active Directory, or any other external provider will be automatically mirrored to your default directory, by creating a new account in your default directory.

If an account already exists in your application’s default directory, Stormpath does not automatically link them. This is to prevent accidental merges, without consideration to your application’s data model. If this behavior is desired, however, you may use the matchingProperty setting to tell Stormpath to match accounts based on their email. When turned on, Stormpath will check for a pre-existing account with the same email in the default directory, and automatically create a link between the two accounts.

Happy Coding!

By enabling account linking in your application, your end users can login to your application via multiple social accounts without extra development effort on your side. Stormpath’s account linking gives you ultimate control over when your accounts get linked as well. In the near future, you can expect us to continue to simplify the social login process, with better and easier social login integrations.

Account linking can be enabled in the Stormpath Admin Console and can be programmatically controlled through the Stormpath REST API today. We’re excited to see what you build with Stormpath!

Using one of the SDKs? Track when manual account linking is in the Node.js, Java, Python, .NET, PHP, and Ruby SDKs.

Questions? Tweet @goStormpath for answers, or email us at [email protected] with any questions you have!