Enterprise SSO — federated login for Fortune 500s and schools

Every enterprise identity provider claims to implement the standard. None of them implement the same one.

The problem

Enterprise and school customers don't create passwords — they log in through their own identity provider, and each one hands back a differently-shaped token. Onboarding a customer can't mean a bespoke auth path per customer.

The approach

• A provider registry, not a pile of branches. An abstract provider declares its id, allowed email domains, and overridable hooks for pulling email, external id, aliases and name out of a decoded token. Adding a customer is a subclass plus a domain-map entry, feature-flag-gated for a staged rollout.
• A resolution ladder. Login resolves a user by federated uid, then external id, then email, then provider-declared aliases — creating the account only if none match, with an integrity-error catch for the concurrent-first-login race.
• Deleting the widget. The hosted third-party login UI came out in favour of ~180 lines of first-party React driving the auth SDK directly: a net −686 lines, three dependencies dropped, three redirect routes collapsed into one, and the removal of a 15-second forced page reload that had been papering over stuck redirects.
• Per-provider reality. One customer's SAML assertion puts the email in a non-standard attribute. Another's OIDC tokens sometimes carry no email claim at all. Both are handled in the provider subclass and covered by tests against realistic decoded tokens.

Stack

Django · Firebase Auth · SAML 2.0 · OIDC · OAuth 2.0 · Microsoft Entra · React · TypeScript

Outcomes

• Four identity protocols supported behind one interface, with named enterprise and school customers onboarded onto it.
• A new account permission decoupled product access from staff status and feature flags, with admin-side validation refusing the grant to users who lack the prerequisite.
• A token-refresh stampede eliminated by collapsing concurrent refreshes behind a single in-flight promise, so parallel 401 retries share one refresh.

What I learned

1. The best bug I fixed was a false alarm that wasn't. A paging alert fired during a customer's SAML login burst. Correlating identity-provider logs against the failing session showed it was bracketed by a dozen successful logins on the same provider — including the same device seconds either side. The cause was a consumed one-time SAML assertion being replayed on the redirect-result path by a reload, a back navigation, or a bfcache restore. The fix mints a fresh assertion on one capped retry rather than suppressing the error.
2. Cap your retries or you build a trap. That retry count is persisted across the redirect and capped at one, specifically so a genuinely broken provider can't put a user in an infinite redirect loop.
3. Write down what the gate does and doesn't do. Domain-only gating on a shared OAuth provider is safe only while the app registration is single-tenant — a property configured in a console, not enforced in the diff. That belongs in the PR description, because the next person will assume the code is the whole story.