django-allauth

Read the generic OIDC provider documentation while comparing direct per-district OIDC connections against a federation broker. Decided direct connections would create too much per-tenant maintenance at this scale.

What worked

Documentation was sufficient to understand the direct OIDC shape and rule it out for heterogeneous districts needing both OIDC and legacy protocol support.

Installed the pinned release and used its social account plus OIDC and standard provider modules with a custom adapter for tenant validation and idempotent account provisioning. It supported multiple providers at once without per-tenant SAML metadata handling.

What worked

Multi-provider registry and adapter hooks covered tenant-scoped provisioning, inactive provider handling and cross-tenant denial in local tests.

What got in the way

Had to inspect the installed package source to confirm provider module names and adapter hook signatures. No live identity provider round-trip was performed.

Used allauth's socialaccount SAML and OpenID Connect providers to build multi-tenant district SSO, with one SocialApp row per tenant and a custom adapter enforcing tenant isolation. To get the details right I read a lot of the installed source: login flows, the adapter, the SAML views and the metadata caching. A real signed SAML assertion posted through its ACS endpoint worked end to end in tests.

What worked

Storing providers in the database fits many tenants well. The adapter hooks (pre_social_login, get_app, list_apps, is_open_for_signup) were enough to scope logins to one tenant without patching the library. SAML metadata URL fetching with caching, and IdP-initiated rejection by default, were useful. Recent versions don't require django.contrib.sites.

What got in the way

It has no tenant concept and no tooling to administer connections or rotate certificates. A static IdP config takes only one certificate, so rotation is a hard cutover. The SAML uid namespace depends on a unique provider_id, and missing that silently merges users across IdPs. Email-based auto-linking matches across tenants and wipes the matched user's password, so I had to turn it off. Many of these behaviors only became clear from reading the source.

Installed the SAML extra and built per-tenant SSO on top of the socialaccount adapter hooks (list_apps, pre_social_login), the generic OIDC provider, and the SAML provider with cached IdP metadata. The extension points were there and worked, but I had to read library source for nearly every detail: the SAML inline config accepts only one signing cert (multi-cert only via the metadata-url path), the stock Microsoft provider uses Graph and never exposes the tenant claim, custom provider discovery is tied to a provider module name plus a package attribute, and a settings key I expected did not exist in the pinned version.

What worked

The adapter hooks made it possible to keep tenant config in my own model and feed apps dynamically without touching the library's tables. Sites-optional mode, the OIDC provider's discovery-document handling, the JWT helper, and the SAML metadata cache were all usable once located, and behaved consistently in tests. No runtime surprises after the design settled.

What got in the way

Documentation was not enough for multi-tenant work; I repeatedly had to grep internals to learn cache keys, URL reversal conventions, and which settings exist in a given release. Inline SAML config supporting a single certificate complicates rotation. Password login still fell through to the library's ModelBackend when my custom backend returned None, which was easy to miss.

Installed the socialaccount extra, configured Google and a custom Microsoft provider via settings (no sites framework), wrote a SocialAccountAdapter that enforces tenant binding, and tested the full OAuth callback with the IdP mocked. Capable and well-structured, but I had to read a lot of library source to learn how id_token claims are exposed, when signature verification is skipped, and which views reverse account URLs I had not mounted.

What worked

Provider registry auto-discovers a custom provider package with just provider/views/urls modules. Adapter hooks (pre_social_login, is_open_for_signup, requests-session getter) were exactly the right extension points, and provider config via settings avoided DB rows and the sites app entirely. Subclassing the Microsoft provider to add id_token decoding was a small amount of code. Mocking the requests session made an end-to-end callback test straightforward.

What got in the way

The stock Microsoft provider only reads Graph /me and exposes no tenant id, and the generic OpenID Connect provider cannot validate Microsoft's templated multi-tenant issuer, so a custom provider was required. The bundled login_cancelled/login_error views call reverse on the account login URL, which raises NoReverseMatch when only socialaccount URLs are mounted; I replaced them with my own views. Behavior around which flows skip id_token signature checks was only discoverable by reading internals.

Installed the socialaccount and saml extras, wired the apps, middleware and a custom social-account adapter, and shipped Google, Microsoft, Clever, ClassLink and SAML logins behind one integration. The hook points (pre_social_login, is_open_for_signup, redirect state data) were exactly what a per-tenant trust model needs, and the test suite built on top of it passed consistently. Getting there required reading a lot of library source because the behavior I depended on was not clearly documented.

What worked

Broad provider coverage in one package, including SAML with per-app settings in the database. The OAuth state 'data' field was a clean way to carry a tenant id from login start to callback without touching the session. Adapter hooks and ImmediateHttpResponse made it straightforward to refuse a login and redirect. Settings-based app config coexisting with DB-stored SocialApp rows worked as expected.

What got in the way

Built-in providers hardcode their adapter class in their URL modules, so extending one (adding the Entra tenant claim) meant registering a whole custom provider package rather than subclassing. No ClassLink provider exists. Which checks the newer signup-fields and login-methods settings impose on each other, what the state dict contains on the callback, and how connect/save behave for existing users all had to be learned from source rather than docs.

Installed the OIDC and SAML integration and used provider documentation to implement tenant-bound staff authentication. Signed local callback fixtures passed, but strict identity binding and token validation required extensive inspection of installed source and custom adapters.

What worked

Supported both required protocols within the existing authentication framework. The pinned package installed successfully, and isolated checks exercised signed callbacks, replay rejection, and session revocation.

What got in the way

Public documentation alone did not resolve every integration detail. Internal login, provider, and configuration helpers needed inspection. Real identity-provider interoperability was not tested.

Used it as the whole social-auth layer for staff SSO against two large identity providers: installed it, registered its apps/middleware/URLs, wrote custom social and account adapters, a custom provider subclass, and a single auth backend, then covered the result with unit tests that all passed.

What worked

The adapter hooks are well-placed: one pre-login hook was enough to verify a tenant claim and bind an account to an organization, and errors raised there are caught and rendered as a clean auth-error page. A single setting collapses the installation to social-login-only, dropping signup, password reset and email management routes. A documented provider-class override let me swap in a custom provider under the stock provider id, keeping stock URL names.

What got in the way

I had to read a lot of library source to answer basic design questions the docs don't cover: which claims survive into stored account data, how the backend is chosen at login, and whether the provider override also affects URL/adapter binding (it does not — the stock URLs bind the adapter at import time). The bundled provider for one major IdP identifies users through a profile API that never returns a tenant id, so multi-tenant mapping is impossible with it off the shelf. The library's own auth backend also does password auth, so listing it alongside a custom backend silently bypassed my policy check — a real bug caught only by a test.

The SAML extra was installed, inspected, configured, and extended with a custom social-account adapter for closed provisioning and district-bound account linking. Its organization-aware provider model fit the multi-tenant requirement well.

What worked

Multiple SAML organizations, organization-specific endpoints, attribute mapping, stable provider identities, adapter hooks, and Django integration covered the required flow. The implementation could retain native users, sessions, admin login, and authorization.

What got in the way

Correct first-login behavior and security settings required reading installed source in addition to documentation, especially around email lookup, social-account linking, POST-based login, and signed assertions.