Account linking

Ory supports four types of account linking:

• Manual account linking through account settings.
• Account linking during login with a social login or single sign on provider.
• Automatic account linking for imported users without additional user interaction.
• Automatic account linking for Google and Apple consumer accounts based on verified email addresses.

Manual account linking

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

Users can link and unlink accounts:

• to start signing in with a profile created in a social login provider when they originally signed up with email and password
• to link another social login provider to their profile so that they can sign in with their GitHub profile and their Facebook profile
• to remove a social login provider link from the profile (possible only when multiple login 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 login provider.
2. Go to your project's Ory Account Experience at https://$PROJECT_SLUG.projects.oryapis.com/ui/registration 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 login provider.

Unlink accounts

Users with multiple login methods can unlink social login 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 login methods available.
2. Go to Account Settings and navigate to the Social Sign In section.
3. Use the buttons to unlink a social login provider.

Account linking on login and registration

Users can link their accounts to social login providers during login or registration. This is useful when users sign up with a social login provider and later want to link their account to another social login provider or to an email and password account:

1. The user creates an account with the identifier alice@example.com, which is also a verifiable address, and a login method such as a password or passkey.
2. When signing in later, the user signs in with a SSO login provider. That SSO account (through the OIDC userinfo endpoint or the ID token) returns a verified or unverified email of alice@example.com. Email verification is not required for this flow due to the verification step that follows (e.g. entering the password of the account to be merged).
3. Since the email address already exists, the user will be prompted to enter the password chosen in step 1.
4. After entering the correct password, the SSO provider is linked to the user's account. Now they can sign in with either password or SSO provider.

Automatic account linking for imported users

In some migration scenarios, the legacy system may only store the email address of the SSO user, but not the subject identifier typically used for performing SSO flows. To solve this migration case, automatic account linking can be used. This allows users to sign in with a social login provider without having to enter their password, as long as the email address is verified and the email address is already associated as a verifiable address with an account in Ory.

To enable automatic account linking for a specific user, import the user into Ory with the oidc credentials using the createIdentity or batchPatchIdentities API endpoints. The payload of an individual identity would look like this:

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-oidc@example.org"
    // Depending on your identity schema, you may include additional traits here
  },
  "credentials": {
    "oidc": {
      "config": {
        "providers": [
          {
            "provider": "github",
            "subject": "the-email@example.org",
            "use_auto_link": true
          }
        ]
      }
    }
  }
}

Additionally, your Ory project must have the use_auto_link feature flag enabled. To enable it, please reach out to Ory support or your account executive. This feature is only available for Ory Network or self-hosted enterprise customers.

Automatic account linking for Google and Apple

Ory supports automatic account linking for Google and Apple consumer accounts. When you enable this feature, users who sign in with Google or Apple are automatically linked to an existing account if both identities share the same verified email address. No additional verification step, such as entering a password, is required.

This is useful when you want a frictionless sign-in experience for users who already have an account and later sign in with Google or Apple using the same email address.

How it works

1. A user creates an account with the email alice@example.com and a login method such as a password.
2. The user later signs in with Google or Apple. The provider returns a verified email of alice@example.com.
3. Ory checks that the email is verified both by the provider and on the existing identity.
4. Because both conditions are met, Ory automatically links the Google or Apple account to the existing identity.
5. The user is signed in without needing to enter their password.

Restrictions

Automatic account linking is only available for the following providers:

• Google — consumer accounts (gmail.com) only. Google Workspace accounts are excluded because expired domains can be re-registered by an attacker, allowing them to take over accounts associated with that domain.
• Apple — all Apple ID accounts.

Other providers such as GitHub, GitLab, or generic OIDC providers don't support automatic account linking.

Enable automatic account linking

To enable automatic account linking, set the account_linking_mode on the provider configuration to automatic.

Ory Console

1. Go to Authentication → Social Sign-In (OIDC) in the Ory Console.
2. Open the configuration for your Google or Apple provider.
3. Set the Account Linking Mode to Automatic.
4. Click Save Configuration.

Ory CLI

1. Download the Ory Identities config from your project:

   ory get identity-config --project <project-id> --workspace <workspace-id> --format yaml > identity-config.yaml

2. Add account_linking_mode: automatic to the provider configuration:

   selfservice:
     methods:
       oidc:
         config:
           providers:
             - id: google
               provider: google
               client_id: ....
               client_secret: ....
               account_linking_mode: automatic # Enable automatic account linking
               mapper_url: "base64://{YOUR_BASE64_ENCODED_JSONNET_HERE}"
               scope:
                 - email
                 - profile
         enabled: true

3. Update the Ory Identities configuration:

   ory update identity-config --project <project-id> --workspace <workspace-id> --file identity-config.yaml

The account_linking_mode setting accepts the following values:

Value	Description
verify_with_existing_credential	Default. Users must verify their identity with an existing credential before linking.
automatic	Automatically link accounts when the provider verifies a matching email address.

Security requirements for automatic linking

For automatic linking to succeed, all of the following conditions must be true:

• The provider is Google (consumer account) or Apple.
• The provider has verified the user's email address (email_verified claim is true).
• The existing identity has the same email address as a verified address.
• For Google, the account must not be a Google Workspace account (no hd claim in the ID token).

Account linking security considerations

Ory doesn't support fully automatic account linking for arbitrary social login providers. This restriction is in place to mitigate several classes of account takeover attacks. Even though automatic linking can improve UX, it opens up critical security risks for most providers. Below are the threat models that justify this decision.

Automatic account linking is available only for Google and Apple, which meet strict security requirements. See the conditions for safe automatic linking section for details.

Risks from verified email addresses

Automatic account linking typically relies on verified email addresses returned by social login providers. This isn't sufficient to prove identity in many real-world cases:

Email domain control is not proof of identity

An attacker can register a domain like acme.org (e.g. because it expired) and configure an email john.doe@acme.org. If your app uses automatic linking and trusts the email john.doe@acme.org as proof of identity, this attacker could take over an existing user's account if they used the same email.

Even worse, many companies expose dangling CNAMEs or unused subdomains. If an attacker can hijack a subdomain (e.g., email.acme.org), they may also be able to receive email for *@email.acme.org, enabling targeted takeovers.

Email address re-use

Many identity systems—especially corporate IAMs or consumer-grade email providers—allow re-creating previously used email addresses. For example:

• A former employee leaves and the company reassigns jane.doe@company.com to a new hire.
• A consumer email service recycles unused email addresses.

In both cases, a new person ends up with a previously owned address. If automatic linking were enabled based on the email alone, the new person could gain access to the old user's account.

Inconsistent or unverified OIDC claims

Social login providers vary in how they handle and expose the email_verified claim. Some always set it to true even if they haven't verified the email properly. Others provide partial or incomplete OIDC claims. Relying on these can create false trust in identities.

Additionally, users can sometimes change their email address with the provider (e.g., Google, GitHub) without re-verification, which invalidates the previous link’s integrity.

Summary of security risks

Threat	Description	Risk
Domain spoofing	Attacker controls domain or subdomain to receive email	Full account takeover
Email re-use	Providers or companies recycle email addresses	Unauthorized access
Weak identity proof	OIDC claims may be unverified or modifiable	False identity linking
Dangling DNS	Subdomains with CNAME takeovers enable abuse	Malicious registration

Ory’s security model

To avoid these risks:

• Ory requires an additional verification step, like password or passkey input, before linking a new login method for most providers.
• Automatic account linking is only allowed for pre-provisioned identities where you explicitly configure the trusted linkage using the use_auto_link flag via the API.
• The use_auto_link feature isn't enabled by default and only available for Ory Network and Enterprise customers after security evaluation.
• For Google and Apple, Ory supports automatic account linking based on verified email addresses because these providers meet strict security criteria.

Conditions for safe automatic linking

Ory allows automatic account linking only for providers that meet all of the following criteria:

• Strong verification of email ownership: The email_verified claim must be reliably set only after a secure email verification process.
• No email address reuse: Once an email address has been used, it must never be reassigned to another user.
• Trusted domains: The provider must control and protect its domains (e.g., gmail.com, icloud.com) and prevent misuse via dangling subdomains or unowned DNS entries.
• Immutable identifiers: Changes to the user’s email address must not silently affect the linked identity without re-verification or user intent.

Currently, the following providers meet these standards:

• Google (Gmail): Strong domain control, verified email, and no email recycling. Google Workspace accounts are excluded because expired domains can be re-registered by an attacker.
• Apple (iCloud): Verified identities and strict lifecycle policies.

Troubleshooting

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.