[Design Discussion] Account Linking and Attribute Syncing for External IDPs

[sadilchamishka]

Related Feature Issue

#3032

Problem Summary

Today, account linking is based solely on the sub claim of the ID token received in the OIDC flow. This works for JIT-provisioned users — they are linked to the local user via sub at provisioning time — but there is no way to link a federated identity to a pre-existing local user that was not JIT provisioned. We should be able to configure which attributes are used to match an incoming identity against local users.

High-Level Approach

This proposal extends the IDP attributeConfiguration model introduced in [1] with two new concerns: account linking (how an incoming federated identity resolves to an existing local user) and attribute syncing (how external attribute values are reconciled with the local account on subsequent logins).

[1] #3157

Architecture Overview

{
    "name": "Google",
    "type": "OIDC",
    "properties": [ "..." ],
    "attributeConfiguration": {
        "userTypeResolution": {
            "externalAttribute": "user_type",
            "valueMapping": {
                "employee": "Employee",
                "customer": "Person"
            },
            "default": "Person"
        },
        "accountLinking": {
            "attributes": [
                { "externalAttribute": "email" }
            ]
        },
        "syncPolicy": {
            "default": "overwrite",
            "attributes": [
                { "externalAttribute": "given_name", "policy": "preserve-local" },
                { "externalAttribute": "hd", "policy": "idp-profile" }
            ]
        },
        "userTypeAttributeMappings": [
            {
                "userType": "Person",
                "attributes": [
                    { "externalAttribute": "given_name", "localAttribute": "firstName" },
                    { "externalAttribute": "address.email", "localAttribute": "email" },
                    { "externalAttribute": "org_name", "localAttribute": "orgName" }
                ]
            }
        ]
    }
}

Account Linking

"accountLinking": {
    "attributes": [
         { "externalAttribute": "email" }
    ]
}

When no local user is found by subject identifier, the listed external attributes are used to look up an existing local user. The lookup semantics are:

1. The external attribute value is taken from the incoming identity.
2. The attribute is resolved to its local attribute via userTypeAttributeMappings for the resolved user type.
3. The mapped local attribute must be an indexed attribute in the system — this is validated at IDP create/update time, the same way localAttribute targets are validated against the user type schema today.
4. On exactly one match, the federated identity is linked to the local user by recording the subject identifier (see below). Subsequent logins resolve via the subject directly.
5. On multiple matches, the login proceeds without linking (JIT provisioning or flow-defined behavior applies) — we never link to an arbitrary match.

Each entry is an object in attributes array, rather than a bare string so per-attribute options can be added later without a breaking change (e.g., requireVerified: true to only link when the IDP asserts email_verified). Also which attribute should

Storing linked identities

The same local user can be linked to multiple IDPs (e.g., Google and GitHub social logins). Instead of a single system attribute { "sub": "<subject-id>" } with the entity identifier indexed as sub = <subject-id>, we store below under system attributes:

{
  "federatedIdentities": [
    { "idpId": "<google-idp-id>", "subject": "<google-subject>" },
    { "idpId": "<github-idp-id>", "subject": "<github-subject>" }
  ]
}

The entity identifier index becomes a composite key <idp-id>:<subject>, so multiple subject identifiers stay indexed per user.

Attribute Syncing

"syncPolicy": {
    "default": "overwrite",
    "attributes": [
        { "externalAttribute": "given_name", "policy": "preserve-local" }
    ]
}

On every federated login after the first, mapped attribute values may have changed at the IDP. The syncPolicy block controls how those values are reconciled with the local account. default sets the overall policy; per-attribute entries override it.

Policy	Behavior
none	Value is used for the login flow only; never written to the local account.
overwrite	Local value is replaced with the incoming value on every login.
preserve-local	Written at first provisioning/linking only; existing local values are never modified.
idp-profile	Stored under the user's IDP profile (the per-IDP federatedIdentities entry) instead of the regular user attributes.

Note: sync policies govern subsequent logins. First-time provisioning always writes the mapped attributes.

IDP profile attributes

The subject identifier is already stored per IDP by default. The idp-profile policy lets additional attributes be stored against the same per-IDP entry — useful for values that are meaningful only in the context of that IDP (e.g., the IDP-side org domain) and that should not collide across IDPs:

{
  "federatedIdentities": [
    { "idpId": "<google-idp-id>", "subject": "<google-subject>", "domain": "abc.com" },
    { "idpId": "<github-idp-id>", "subject": "<github-subject>", "domain": "abc.io" }
  ]
}

Attributes that should participate in the regular user profile (and be overwritten on sync) are recommended to be mapped to local attributes as usual; idp-profile is for IDP-scoped data.

API exposure

federatedIdentities is a system attribute. It is exposed only through dedicated APIs (e.g., listing a user's linked accounts, viewing linked-account details, unlinking) — never through the general user attribute APIs.

Security Considerations

• Linking attributes should be ones the end user cannot freely self-assert at the external IDP. For email-based linking, the IDP should be one that verifies email ownership (e.g., asserts email_verified); otherwise an attacker could set a victim's email on their own IDP account and get linked to the victim's local account.
• If the linking lookup matches more than one local user, no link is recorded and the login proceeds per flow configuration.

Questions for Community Input

1. Should linking require an explicit user consent/confirmation step (interactive flows) before the link is recorded, or is silent linking acceptable?
2. Behavior when the linking attribute matches a user of a different user type than userTypeResolution resolves to — reject, or link anyway?
3. Should unlink be self-service via user APIs, admin-only, or different API?

[ThumulaPerera]

Regarding Account Linking,

On multiple matches, the login proceeds without linking

Currently in ThunderID, same federated user can have multiple local accounts in different OUs. For such cases, in the login flow, we can configure an executor to disambiguate the user. Given this, proceeding without linking for multiple matches is not the correct approach IMO. What if we link all matching local accounts to the same federated user in such cases?

[sadilchamishka]

First we can link with one user, so that resulting merge profile is simple.
We can keep open for the mentioned use case and decide how to process in such cases.

[ThumulaPerera]

On Questions for Community Input,

2. I think even in general, rejecting makes more sense here. With the proposed approach, I think we should specially reject because it might otherwise lead to correctness isssues.

For example

"accountLinking": {
    "attributes": [
        { "externalAttribute": "username" }
    ]
},
"userTypeAttributeMappings": [
    {
        "userType": "Student",
        "attributes": [
            { "externalAttribute": "username", "localAttribute": "name" }
        ]
    },
    {
        "userType": "Teacher",
        "attributes": [
            { "externalAttribute": "username", "localAttribute": "username" }
            { "externalAttribute": "fname", "localAttribute": "name" }
        ]
    }
]

There are two User A and B.

A : username at External IDP is tom. name at Thunder local store is tom.
B : username at External IDP is harry. username at Thunder local store is harry.
fname at External IDP is tom. name at Thunder local store is tom.

A logs in. User type resolves to Student. So local store search is done for users with name=tom. 2 local users will match. A whose type is Student and B whose type is Teacher. Linking A is correct but liking B is wrong.

[sadilchamishka]

Yes that is a valid scenario.
If the IDP could communicate that TOM is an student, the userTypeResolving mechanism could identify that account linking should be scoped to that user type. Even if two accounts exist how the profile merging is the concern where we left without profile merging at first phase.

Though the architecture extensible for advanced edge cases, most of the B2C use cases might just configure as follows and users with corresponding email will be linked. No user type resolve, attribute mapping etc..

"accountLinking": {
    "attributes": [
        { "externalAttribute": "email" }
    ]
}

[sadilchamishka]

We need to plan on UX designs for simplifying the configurations and at least keep documented the advance configuration capabilities for those who need complex integrations.