Identity and account mapping

Store a central identity as the exact (issuer, subject) pair. Keep your own immutable local account ID and an explicit central Institution-to-local tenant mapping. Email, username, and display name are attributes, not linking keys. This rule prevents two people with the same address from sharing access and preserves an account through an email change.

Map a successful login

1. Validate the signed OIDC ID token for your client, issuer, audience, nonce and time bounds.
2. Look up the existing local link by (iss, sub) in the product’s durable account table.
3. Check that the linked account still belongs to the selected local tenant and has the required product role.
4. Check current signed lifecycle eligibility before issuing a protected product session.
5. Refuse access when any link, membership, product approval, or freshness check is missing.

One person can belong to multiple Institutions. Scope every product query to the selected Institution and local tenant. A central product eligibility grant does not invent a product role.

Link an existing account

The reviewed link workflow starts with a five-minute challenge. The person proves the existing local account with a fresh local credential and confirms the central identity through a purpose-bound OIDC callback. A different live Institution sponsor approves the exact local account, central issuer and subject, project, and Institution. The product’s separately approved machine identity attests the proof. A typed evidence reference alone is insufficient.

The management API exposes /v1/link-challenges and scoped challenge read, attest, approve, request, and exact acknowledgement routes. The product installs the approved link metadata with the corresponding lifecycle entity in one transaction, then acknowledges that exact version and proof. A generic cursor acknowledgement does not make a link effective. Pending approval, delivery, or acknowledgement is not product access.

Revoke and rehire

A departure or suspension removes the current authorization and should end local sessions. Rehire needs fresh sponsorship and product review. Never restore historical roles or clear a local reapproval requirement because an old (iss, sub) appears again. Test duplicate emails, changed emails, multiple Institutions, revoked sponsors, stale entity versions, and mismatched acknowledgements.