Use the issuer and subject as the login identity
For a SaaS application accepting more than one OpenID Connect provider, map a validated (iss, sub) pair to an internal person. Keep email as an attribute. When a second identity should reach an existing account, use an explicit linking operation that proves control of both identities and satisfies the tenant's connection policy.
The 14-decision identity fixture makes that choice inspectable. Six lookups resolve a known person twice and leave four different identity pairs unmapped. Eight link decisions produce one new link, one unchanged replay and six denials. Its authentication and authorization evidence is assigned input. It does not validate tokens, authenticate a browser or test persistent-store concurrency.
This separation avoids two incompatible assumptions: that a person's email never changes and that matching email from different providers establishes the same application account. A design that treats email as the principal cannot keep both promises under the examples below.
Separate the person, login identities and memberships
Use an internal person ID for the application account. Attach one or more external login identities to it. Store workspace membership independently, with its roles and lifecycle. The result is a person who can possess several sign-in methods without automatically gaining a membership in every tenant that accepts those providers.
An external identity has an issuer and a subject. OpenID Connect Core, section 5.7 identifies that pair as the stable basis for identifying an end user and warns that email can change or be reused. A subject value from one issuer must not collide with the same text from another issuer. NIST's federation guidance likewise requires accounting for the identity provider when processing a federated identifier.
Treat the configured issuer as an exact identifier. Do not reduce it to a hostname or strip its path. OpenID Connect explicitly distinguishes a subject under https://example.com from the same subject under https://example.com/sales. Configuration discovery and token validation must establish the expected issuer before a mapping lookup accepts it.
The diagram is a proposed storage boundary. It does not demonstrate token security. An actual sign-in flow needs a supported OIDC implementation to verify the token's expected issuer, audience and other required conditions, including its cryptographic and time checks. The mapping function in the download starts after that boundary and receives trusted fixture values.
An issuer can use pairwise subject identifiers to give different relying parties, or groups of them, different identifiers. The Core specification's subject-identifier section describes that privacy mechanism. A change in the relying-party sector may therefore change the subject observed for the same person. Plan an authenticated migration or linking procedure; email equality does not recover the missing identity relationship.
Resolve the changed email without creating a new person
The model initially maps https://idp.example/corporate plus subject-42 to person-a. Its lookup ignores email. An original address and a replacement address consequently resolve the same person. The address can be updated through the application's attribute policy without rewriting identity ownership.
| Executed lookup | Mapping result | Meaning for the design |
|---|---|---|
| Original issuer and subject | person-a | Known login identity |
| Same issuer and subject, changed email | person-a | Contact change preserves account identity |
| Same subject, different issuer | Unmapped | Provider scope is part of the key |
| Same host, different issuer path | Unmapped | Host equality does not imply issuer equality |
| Same email, different subject | Unmapped | Matching address does not merge accounts |
| New pairwise-sector subject | Unmapped | The new pair needs an authorized mapping transition |
Unmapped is a routing outcome, not an instruction to create a person immediately. A tenant enforcing enterprise SSO may require pre-provisioned membership. Another product may permit self-registration. A known person may instead be trying to attach a new provider. Select the allowed next step from the product's provisioning and connection rules.
Do not infer that a verified email makes automatic linking universally safe. Verification has provider-specific scope and a point in time. It does not establish that the incoming identity controls an existing application account, owns its current authenticators or should inherit its tenant permissions. An application may adopt a tightly governed correlation process, but that needs documented trust and lifecycle assumptions beyond comparing two claims.
Make linking a separate authorized transition
The proposed default is user-initiated linking. A signed-in person requests another sign-in method, proves recent control of the current account and authenticates the candidate identity. Bind the linking intent to the expected session, destination account and bounded flow. The callback for this operation must not fall through to ordinary login matching.
Auth0's account-linking guidance recommends authenticating both accounts before linking. That recommendation supports the proof boundary; it does not supply our tenant policy or guarantee a custom application's callback handling. Require the second proof even when the two providers report the same verified email.
At commit, ensure the external identity is still unowned or already belongs to the intended person. A mapping owned by somebody else must be rejected. Enforce uniqueness for the issuer-and-subject pair and implement a transactional claim so two competing requests cannot attach it to different people. The pure dictionary fixture below expresses that policy, but provides no multi-process transaction guarantee.
Tenant authorization remains a separate condition. The current person must be allowed to perform this operation in the workspace context, and the candidate connection must be approved there. Linking a personal provider should not quietly bypass required corporate SSO. A product with a global person record needs to decide how the new identity may be used for each tenant before allowing it to establish tenant access.
| Executed link decision | Outcome | Mapping change |
|---|---|---|
| Both proofs, bound intent and permitted tenant connection | Linked | One identity added to person-a |
| Missing current-account proof | Denied | None |
| Missing candidate-identity proof | Denied | None |
| Linking intent not bound to this flow | Denied | None |
| Person lacks membership in requested tenant | Denied | None |
| Candidate issuer is not an approved tenant connection | Denied | None |
Candidate identity already belongs to person-b | Denied | None |
| Repeat the completed link | Already linked | None |
Run the download with python3 experiment.py and read results.json. Each denied case starts from a fresh mapping and asserts that it remains unchanged. The successful case also asserts that membership did not change. Fourteen outcomes describe this assigned policy; their count is not a security score.
Choose a migration contract instead of an email shortcut
For an existing email-keyed product, preserve internal person IDs before introducing OIDC mappings. Inventory how users currently prove control of those accounts and which workspaces require approved enterprise connections. Then attach validated identities through a migration that records the evidence authorizing each relationship.
A user-driven transition can require the existing sign-in method before accepting the new one. An enterprise-managed transition may rely on an approved provisioning relationship and organization administrators. Those are different authority models. Document the exact evidence, scope and recovery path rather than labeling either procedure an automatic account merge.
If the legacy method is no longer available, follow a deliberately reviewed account-recovery process. Matching an incoming email to a historical row cannot substitute for the missing proof. Keep the recovery decision distinct from ordinary linking, and do not leak whether an address has an account while offering the next step.
The enterprise-onboarding brief connects sign-in, provisioning and employee departure. This article adds the identity key and link transition beneath that workflow. A consultant's workspace removal can revoke that membership without deleting the person or the login identities they legitimately use elsewhere. Conversely, a linked identity does not restore a revoked membership.
Record the conditions that would change the decision
Adopt issuer-and-subject mappings when the product supports multiple providers or changing contact attributes. Keep a separate person record when one individual may use several identities. Use explicit linking when another login method must reach that same person, with current authorization checked at the mutation boundary.
Revisit the decision when an issuer changes, a pairwise-subject sector changes, tenant SSO requirements tighten or identity ownership is disputed. Each event requires a migration, recovery or policy review. None should be handled by globally rewriting identity keys from email.
Acceptance evidence must cross the real protocol boundary: reject a token from an unexpected issuer, authenticate both sides of a link, replay an old linking callback and race two claims for one candidate identity. Test a forbidden tenant connection and removal of membership after a successful link. These are proposed integration tests; the local fixture cannot execute them. Record which flow owns the proof and which transaction owns the identity before enabling the additional sign-in method.
Sources
Documentation checked .
Dreamtsoft Editorial
Editorial follow-up: a successful link does not create workspace membership in this model. Keep the membership decision explicit when introducing another identity provider. Test that boundary independently from identity lookup.