User account linking

Ory allows users to link their accounts to social sign-in providers after they signed up, as well as un-link social sign-in providers they previously added.

info

Users can link their accounts only to social providers you configured in your Ory project.

Users can link and unlink accounts:

• to start signing in with a profile created in a social sign-in provider when they originally signed up with email and password
• to link another social sign-in provider to their profile so that they can sign in with their GitHub profile and their Facebook profile
• to remove a social sign-in provider link from the profile (possible only when multiple sign-in methods are available to prevent locking users out from accounts)

Link accounts

Users can link accounts manually through their account's settings page. To try out account linking, use the Ory Account Experience. Follow these steps:

1. Configure at least two sign-up methods in your Ory project. One of these methods must be through a social sign-in provider.
2. Go to your project's Ory Account Experience at https://$PROJECT_SLUG.projects.oryapis.com/ui and sign up.
3. After you sign up, go to Account Settings and navigate to the Social Sign In section.
4. Select one of the buttons to link an available social sign-in provider.

Unlink accounts

Users with multiple sign-in methods can unlink social sign-in providers from their account through their account's settings page. To try out account un-linking, use the Ory Account Experience. Follow these steps:

1. Go to your project's Ory Account Experience at https://$PROJECT_SLUG.projects.oryapis.com/ui and sign in with a user account with multiple sign-in methods available.
2. Go to Account Settings and navigate to the Social Sign In section.
3. Use the buttons to unlink a social sign-in provider.

Automatic account linking

Users can link social sign-in accounts on login without interaction using a secure flow. This is how it works:

1. The user creates an account with the identifier [email protected] and a password.
2. When signing in later, the user signs in with a social sign-in provider. That social sign-in account (through the OIDC userinfo endpoint or the identity token) contains the same identifier [email protected].
3. Since the identifier already exists, the user can't be logged in directly. Instead, the user will be prompted to enter the password chosen in step 1.
4. After entering the correct password, the social sign-in is linked to the user's account. Now they can sign in with either password or social sign-in provider.

Security considerations

Automatic account linking can be a security risk. Consider this scenario:

1. Your application allows users to create new accounts or sign in with ACME.
2. John creates an account with his email [email protected].
3. Malicious actors create an ACME account for [email protected].
4. They sign up in your app using this ACME account.
5. Your system, detecting duplicate accounts, prompts for account linking.
6. Malicious actors link the accounts, gaining access to John's account.

To prevent this, users need to verify an additional credential before the accounts can be linked. In the scenario above, the malicious actors would be prompted to enter the password associated with the [email protected] identifier.

Hide irrelevant authentication methods

Depending on the use case it might be required to show all configured authentication methods to the user. This can be confusing for users who have accounts with different authentication methods.

To prevent confusion and hide authentication methods that aren't configured for the user, enable login hints. Login hints inform users about the authentication methods available for the existing account.