Somebody else's login
Sooner or later, an app that sells to companies is asked to stop owning its users' passwords. For Drafthall, a service where shipyards and their subcontractors review construction drawings, the request came from Halvorsen Marine, in a contract: its engineers sign in with their corporate accounts, and anyone Halvorsen removes from its directory loses access the same day. Halvorsen's IT department wanted to control every account from its own directory, which a password table inside Drafthall would not allow.
The answer is Federated Identity: the app stops proving who the user is and accepts a statement from an identity provider that someone else runs, across a trust boundary. Halvorsen's provider holds the accounts, passwords and second factors and runs the login. Drafthall receives a signed assertion, in effect "user 7f3a at Halvorsen, signed in a minute ago, for Drafthall", and decides whether to believe it. Why one provider for many apps is worth having is the ground of Authentication: passwords, MFA & identity providers; this article starts where the provider belongs to someone else.
Two protocols carry the assertion
SAML 2.0, the older, XML-based standard, is still what many enterprise directories and legacy business apps speak; its assertion is a signed XML document. OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0, and its assertion is the ID token, a signed JSON Web Token. Both implement this pattern. Plain OAuth 2.0 does not: it delegates authorization, not authentication, letting an app call an API on a user's behalf without by itself telling the app who signed in.
In both, the answer travels back through the user's browser rather than from the provider to the app: SAML usually has the browser post the signed assertion, and OIDC usually has it carry a one-time code that the app exchanges with the provider for the ID token. OAuth 2.0 & OpenID Connect flows covers those redirects and the checks an ID token must pass. This article covers what the protocols leave to the app: whom to trust, and what to do with what they say.
The browser brings back each provider's answer. Drafthall finds its user by issuer and subject.
Which provider is this user's?
One provider did not last. Brekke Welding, a subcontractor, ran a directory that spoke SAML; freelancers signed in with Google; Drafthall's staff had their own. The login page now has to send each person to the right provider before anyone has proven anything. That step is home-realm discovery: the app picks the provider from the email domain typed on the first screen, the per-customer subdomain the user arrived on, or a cookie from last time, and shows a list when none of those decides. This is routing, and the decision that matters comes after it: once a domain is routed to a customer's provider, its users should have no other way to sign in, neither a Drafthall password nor a Google account with the same address, or Halvorsen can remove an engineer and he still gets in.
A trust configuration per provider
Federation means keeping, for each provider, the few facts every assertion is checked against:
- Issuer. The provider's identifier, which the assertion must name exactly:
issin an ID token, theIssuerelement in SAML. - Signing keys. An OIDC provider publishes them at the
jwks_uriin its discovery document and rotates them, so the app fetches new ones when it meets an unknown key ID. A SAML provider usually ships a certificate in metadata imported by hand; when it rotates and Drafthall's copy does not, every sign-in from that customer fails at once. - Audience. Drafthall's own identifier at that provider: its client ID in OIDC, its entity ID in SAML.
One check is particular to federation. Some providers host thousands of organisations and sign for all of them with the same keys, so a correct signature from such a provider can come from any of its customers. The issuer, or the tenant identifier inside the assertion, has to match the one configured for Halvorsen, or an employee of another customer of that provider can open Halvorsen's drawings.
From claims to a Drafthall user
An assertion carries claims, statements about the user: an identifier, usually an email and a name, sometimes groups. Drafthall still needs its own user record, because projects and permissions point at a Drafthall user ID, not at a provider. It keys that record by the provider's stable identifier: issuer plus sub in OIDC, for the reasons OAuth 2.0 & OpenID Connect flows gives; in SAML issuer plus a persistent NameID or an attribute both sides agree never changes. Ask each SAML customer which one they send, because some directories send the email by default, and an email is not an identifier: it can change, or pass to a later employee.
The first time a Halvorsen engineer signs in, there is no record yet. Just-in-time provisioning creates the user from the claims of that first valid sign-in, so nobody at Halvorsen lists engineers in Drafthall's admin screen. It is also where groups become roles: the assertion says hull-design, and a rule configured for Halvorsen alone says that group reviews hull drawings, because one customer's admins means nothing to another. The rule runs again at every sign-in, not only the first, so a group Halvorsen takes away also takes away its role. What a role may then do is Authorization: roles, relationships & policies.
The awkward case is a person who arrives twice. A freelancer has used Drafthall through Google for a year, then joins Brekke and signs in through Brekke's provider with the same address. Attaching the new identity to her old account because the emails match is how accounts get taken over: anyone who can get a trusted provider to assert that address, one that never verified it or lets users edit it, inherits her projects. Account linking is safe when the user first signs in with the existing identity and confirms the link. Linking because a provider Drafthall made authoritative for the domain vouches for the address gives the account to whoever holds that address now, a later employee included.
When Halvorsen removes someone
Back to the contract. Halvorsen disables an engineer's account on a Friday afternoon, so he can no longer sign in at Halvorsen's provider and no new assertion reaches Drafthall. What already exists stays:
- A Drafthall session opened that morning works until it expires, because Drafthall checked the assertion once, at sign-in.
- The user that just-in-time provisioning created is still there, with its roles.
- API keys he created inside Drafthall never pass through the provider.
Short sessions, renewed through the provider, narrow the first gap. The others need Drafthall to learn of the removal: Halvorsen's directory can push the deactivation over SCIM, a standard API for provisioning and deprovisioning users, or Drafthall can poll the directory for it, and Drafthall then disables the user, ends his sessions and revokes what he holds. If neither happens, "the same day" holds only if someone disables the user in Drafthall by hand, because sessions expiring leaves his API keys working. How a revocation reaches every place that holds a session is in Sessions vs tokens: JWT, refresh & revocation.
Build the other side
In the SSO Identity Provider Challenge you design the provider that apps like Drafthall federate with. Its brief asks for OIDC for web apps, SAML for legacy ones, and users and groups synced from the corporate directory. Draw that sync as the path a removal travels as well as a new hire, and write on each app's edge what it checks before believing what arrives: signature, issuer, audience and expiry.