Auth architecture
Single sign-on is the setup guide for
configuring an identity provider. This page is the architecture behind it: why
the auth stack is shaped the way it is, what django-allauth is and is not
responsible for, and how a browser session, a mobile client, and a WebSocket
connection each end up authenticated from the same underlying credential.
The credential: a JWT pair behind an httpOnly cookie
Section titled “The credential: a JWT pair behind an httpOnly cookie”Every session, regardless of how it began (password, OIDC, GitHub), ends the
same way: TruePPM mints a simplejwt access/refresh pair and hands the browser
only the access token in the response body. The refresh token never appears in
JSON at all — it is set directly as a cookie:
- httpOnly — unreadable by JavaScript, so an XSS payload can ride the current access token but cannot exfiltrate the long-lived refresh credential.
SameSite=Strict,Secureby default.- Path-scoped to the refresh endpoint only (
/api/v1/auth/token/refresh/), so it is never attached to an ordinary API call — only to the one request that needs it.
This is the design choice that makes “log in via password” and “log in via
your own IdP” converge onto one session mechanism: an OIDC or GitHub login
does not mint a separate kind of token. It runs RefreshToken.for_user(user)
and sets the identical cookie a password login would, then redirects the
browser to a frontend completion route that calls the ordinary refresh
endpoint. From the moment a session exists, the rest of the application cannot
tell how it began.
A short-lived access token (minutes, not hours) limits the blast radius of a token that does leak somewhere the refresh cookie doesn’t reach — a server log line, a support screenshot, a browser extension with page-script access. The refresh token is rotated on every use and the prior one blacklisted, so a stolen refresh token is a single-use window, not a standing credential.
Rotation has a consequence for anyone running several tabs: every tab of the
same browser shares the one refresh cookie, so a tab that sends the value a
sibling tab has just rotated is refused with the same 401 a replayed, stolen
token gets. The server cannot tell the two apart, and is deliberately not asked
to — a grace period for a just-used token would also be a grace period for a
thief. The browser client absorbs it instead. Refreshes are serialized across
tabs with a Web Lock,
so a reloading tab waits for a sibling’s in-flight rotation and then presents
the rotated cookie. A refresh refused with 401 is retried once after a short
pause, which covers a browser without the Locks API. A session that has really
ended (signed out, revoked, or past its lifetime) is refused again on the retry
and the client shows the sign-in dialog.
Tabs also tell each other. A BroadcastChannel named trueppm-auth carries the
kind of event (session ended, read-only chosen, signed out, session restored),
never a token: a tab that hears a sibling’s sign-in mints its own access token
from the shared cookie. “Session ended” is sent only when the server refused the
session (a 401 from the refresh endpoint, or WebSocket close code 4001); a refresh
that failed on a network error, a timeout or a 5xx ends the session in that tab
alone. A tab that hears “signed out” drops its cached reads as well as its token.
A tab that hears “session restored” asks /auth/me/ with its new token before
going live and clears its cache unless the signed-in user is provably the same
one. Where BroadcastChannel is missing, a tab finds out on
its next request instead. A tab that waits more than a second on a sibling’s
refresh lock shows “Signing in…” in the status bar, and stops waiting after six
seconds and refreshes on its own.
When the session has ended
Section titled “When the session has ended”What the user sees depends on what was at stake. If a change was in flight, or nothing had loaded yet, the blocking dialog appears; its copy says “your last change did not go through” only when a write was actually interrupted. If nothing was in flight and content is already on screen, the client goes straight to a slim read-only banner and leaves focus alone. A tab that lost its session before anything loaded offers only Sign in.
Cached content stays on screen for at most 15 minutes from the moment the tab learned the session ended, behind the dialog or under the read-only banner alike. Choosing Continue viewing, a refused write, and a sibling tab’s read-only choice do not restart it. The client cannot ask the server anything while signed out, so an account deactivated in the meantime would otherwise stay readable for the life of the tab. When the window ends, or when you return to the tab after it has, the client clears its cache and shows the dialog with only Sign in. In read-only mode the first attempted change shows a short notice instead of the dialog; a second one re-opens the dialog.
Which identifier authenticates
Section titled “Which identifier authenticates”The sign-in form asks for an email address, and Django’s ModelBackend matches
on the username column. Those are the same string for some accounts and not for
others — an invited user chooses a username when they accept — so from 0.4
the login view resolves the submitted identifier itself: it tries the
username first, unchanged, and only if that fails looks for the one account
whose email matches. Before 0.4, only the username was matched.
Three properties of that fallback are load-bearing rather than incidental, and each exists because the email column carries no uniqueness constraint:
- Username first, always. The email branch can only ever add a way in. An account whose username happens to be email-shaped keeps its own login, and is never displaced by a different account holding that string as its email.
- Ambiguity fails closed. An address on two accounts refuses both, mirroring the same decision the OIDC account-linking path already makes: picking one of two accounts would sign someone into an identity they did not name, which is worse than asking them to use their username.
- The refusal carries no information. “No account with this email” and “wrong password” return the same status and the same body, and the miss path spends the same password-hash work as the hit path, so the endpoint cannot be used to test which addresses have accounts.
One account also keeps one guess budget. The per-account login throttle runs before the view and can only key on the identifier as submitted, so an account answering to two identifiers would otherwise have two independent budgets; the view therefore checks and charges the resolved account’s own bucket before it spends a second password comparison. Recording without checking would have capped only the email-first order, which is the worse failure — a protection that looks complete and holds in one direction.
The resolution lives in the login view, not in AUTHENTICATION_BACKENDS. A
backend would widen every authenticate() caller in the process — the Django
admin login among them — and would sit upstream of the view’s own
post-authentication policy seam, which is where an Enterprise deployment can
refuse password login for an account governed by enforced SSO.
Why django-allauth is a library here, not the login flow
Section titled “Why django-allauth is a library here, not the login flow”TruePPM’s SSO design went through two generations, and the reasoning for the second is worth carrying forward because it is easy to accidentally undo in a future change.
Generation 1 was a hand-rolled OpenID Connect relying party: TruePPM’s own
code did discovery, PKCE, token exchange, and ID-token validation, with no
allauth involvement. It worked, and it established every security property
the design still has today — but it was OIDC-only. GitHub has no OIDC
discovery document, no JWKS, no ID token; representing it meant either
building a second, GitHub-shaped relying-party path by hand, or adopting a
library that already understands GitHub’s OAuth2 shape.
Generation 2 adopts allauth.socialaccount — but strictly as a provider
registry and metadata source, not as the flow itself. TruePPM never mounts
allauth.urls; there is no /accounts/... route, and no request is ever
handled by allauth’s own views. Every OIDC identity provider (generic,
Google, Microsoft Entra ID, GitLab, Keycloak, Authentik, Zitadel, Okta, Auth0)
registers as a named openid_connect provider app; GitHub is the one entry
using allauth’s dedicated github module, since it has no OIDC surface to
speak of. TruePPM’s own views own the callback path, and that path is
identical for every provider — /api/v1/auth/oidc/callback/ — because the
provider is disambiguated by a slug carried in server-side login state, not
by a URL segment. A stable callback path matters beyond tidiness: it is what
keeps an operator’s provider allow-list, the redirect-URI instructions in
Single sign-on, and OpenTelemetry’s
query-param redaction rule all correct without per-provider special-casing.
The reason plain allauth was not adopted wholesale is that five security properties the bespoke relying party carried would otherwise be lost:
- Egress control. Every outbound request the flow makes — discovery document, token exchange, JWKS fetch — passes through the same SSRF guard described below. Allauth’s own provider code makes these requests directly and does not know about that guard.
- Secret-at-rest. Allauth’s
SocialApp.secretfield is plaintext. TruePPM stores the client secret Fernet-encrypted on a side-row (SsoProviderPolicy) instead and leavesSocialApp.secretempty. - Stable, redactable callback path — covered above.
- ID-token validation discipline — an explicit algorithm allow-list
(asymmetric algorithms only;
noneandHS*are rejected outright, closing the classic alg-confusion attack), a fail-closed allowed-domain gate, and a browser-binding cookie (below) — none of which allauth’s generic OIDC provider enforces on its own. - The JWT bridge — the SPA needs the simplejwt refresh cookie described above, not a Django session, which is what allauth mints unassisted.
So the rule going forward is: allauth supplies provider metadata; it never
opens a socket. Any change that routes a request through allauth’s own
client code instead of TruePPM’s egress module would silently reintroduce
the SSRF gap generation 1 closed.
Authorization Code + PKCE, and the durable identity binding
Section titled “Authorization Code + PKCE, and the durable identity binding”For an OIDC provider, TruePPM acts as a relying party using the Authorization Code flow with PKCE — mandatory, not optional, on every configured provider. The flow that matters architecturally:
- Login start mints a single-use
state, a PKCE verifier/challenge pair (S256), and anonce; stores them server-side keyed bystate(5-minute TTL); and additionally sets a browser-binding cookie carrying the samestatevalue, httpOnly,SameSite=Lax. - Callback compares the
statequery parameter against that cookie (constant-time) before consuming the server-side state. This is a distinct check from state-replay protection: server-side state proves the server issued this authorization response; the cookie proves the same browser that started the flow is the one completing it. Without it, an attacker could complete their own login at the identity provider and hand the resulting callback URL to a victim, silently signing the victim into the attacker’s account — a login-CSRF / session-fixation class of attack.SameSite=Lax(notStrict) is required here because the callback is a top-level navigation arriving from the identity provider’s origin, whichStrictwould otherwise strip. - ID-token validation checks signature (against the provider’s JWKS,
fetched through the SSRF guard — deliberately not using PyJWT’s own
PyJWKClient, which opens its own socket and follows redirects, bypassing the guard entirely), issuer, audience, expiry, and thenoncebound at login.
The identity that then resolves to a TruePPM account is bound to the durable
(issuer, subject) pair, never to the mutable claimed email. A subject
already linked under one issuer that reappears under a different issuer
fails closed rather than silently re-linking — this is what makes re-pointing
a provider to a new issuer a “remove and re-add” operation
(Single sign-on)
rather than an in-place edit: an in-place issuer change would otherwise let an
unrelated account at the new issuer, whose subject happens to collide with an
old binding, take over that binding.
Silent account linking is notified, not blocked (2026-09-14, #3554; Owner/Admin amended 2026-10-25, #4651)
Section titled “Silent account linking is notified, not blocked (2026-09-14, #3554; Owner/Admin amended 2026-10-25, #4651)”The one case above where an OIDC/OAuth identity binds to a TruePPM account the
IdP did not create — the durable-identity resolution failing to find a match
by (issuer, subject), then a verified email matching an existing local
user — grants a federated credential to that account with no
re-authentication step. ADR-0517 (see Architecture Decision
Records) already named this as a risk it
deliberately re-verified rather than closed (its Consequences section:
“Account-linking-by-verified-email takeover is the same risk as ADR-0187 and
must be re-verified on the new models”). Issue #3554
is that re-verification, run as a threat-model + ai-review gate pass
against this surface, and it forced an explicit choice among three responses:
notify the account, block the link for admin/owner roles pending a one-time
re-auth, or accept the risk and only document it.
Decision: notify, not block. The bar for this link is control of a
verified mailbox at an allowed domain (or an IdP that mis-asserts
email_verified) — the same bar password reset already accepts, with one
difference: a password reset is visible to the account it targets (an email,
revoked sessions), and this link was not. Closing that gap only needed a
notification, not a new authentication step, so TruePPM emails the linked
account — naming the provider and the approximate time — the first time this
branch runs, deferred until the database transaction that creates the binding
commits (so a link that is rolled back never sends a notice for a binding
that was never persisted), and sent best-effort (a mail-transport failure
never fails the sign-in). It applies to every workspace role the linked
account may hold, Owner included — the risk does not vary by role, only its
blast radius does. See
Single sign-on for what
the account owner sees.
Blocking the link outright for Admin/Owner roles — requiring a one-time password re-auth on the completion page before the identity binds — was considered and deliberately deferred rather than rejected (taken up on 2026-10-25, see the amendment below): it is a real additional control for the highest-privilege accounts, just not one the owner asked for in this pass. It remains open as a follow-up if the team decides the notification alone is not enough.
Amendment (2026-10-25, #4651): Owner and Admin are now blocked. #4629 already
refused the first-time email link onto superuser and staff accounts, on the
reasoning that a verified IdP email is a claim about a mailbox, not proof the
caller owns a privileged local account. TruePPM’s own top tiers are the
workspace Owner and Admin roles, and an account promoted to them in-app
is neither superuser nor staff, so it still linked on the first assertion: whoever
controlled the matching address at the IdP signed in as the Owner, and the
notification above went to that same mailbox. The deferred block is therefore
taken up. The first-time link is refused with the same SSO_NO_MEMBER outcome
for any account whose workspace role is Admin or higher, before any binding is
written. There is no operator setting to opt back in. Members, and every
account that already has a linked identity, are unaffected, and the notification
remains for the accounts that still link by email. An authenticated “link my
identity” flow for the blocked accounts is tracked in #4634; until it ships they
are linked by an operator or keep using their password.
The WebSocket ticket
Section titled “The WebSocket ticket”A browser cannot attach an Authorization header to a WebSocket upgrade
request, so some form of credential has to travel in the connection URL
itself — and a URL is exactly the part of a request that access logs, load
balancers, and proxies routinely persist. A 15-minute access token sitting in
a query string is therefore a 15-minute window of credential exposure in
every log that captured it, which is a materially worse trade than the same
token in a header nothing logs by default.
The fix is a purpose-built, single-use ticket, not the access token itself:
POST /api/v1/ws/ticket/(any authenticated caller) mints a 256-bit random ticket, stores it directly in Redis — not Django’s cache framework, because the Channels consumer runs in a separate process from the request that would populate an in-process cache — keyedws:ticket:<ticket>→ the caller’s user id, with a 30-second TTL.- The client opens the socket with
?ticket=<id>in place of a token. - The consumer consumes the ticket with an atomic Redis
GETDEL— read-and-delete in one operation, so the ticket is single-use by construction. A replayed or raced second attempt to consume the same ticket resolves to nothing, even if a log somewhere captured the URL: by the time anyone reads that log, the ticket has already been spent.
The ticket authenticates the connection; it does not authorize it. Once the consumer has resolved a user from the ticket, it still runs the project-role gate described in RBAC and permission architecture before admitting the connection — minting a ticket proves who you are, not that you may join this particular project’s channel.
A raw ?token=<jwt> query parameter is still accepted as a deliberately
temporary, off-by-default fallback (behind an operator flag), logged as a
deprecation warning whenever it’s used, so operators can find any client
still depending on it before it is removed.
Outbound requests are never trusted by default
Section titled “Outbound requests are never trusted by default”Every outbound call the auth stack makes on an operator- or user-influenced
URL — an OIDC provider’s discovery document, its JWKS, its token endpoint,
GitHub’s API — passes through the same egress guard the rest of the platform
uses for webhook delivery, personal-access-token verification, and git-link
status checks. It resolves the target hostname and refuses to proceed if any
resolved address is not globally routable — covering private (RFC1918),
loopback, link-local, and cloud-metadata (169.254.169.254) address space —
and disables redirect-following so an already-validated URL cannot bounce the
request somewhere unvalidated afterward.
The one case this guard has to make room for is an identity provider an
operator runs inside their own cluster, which by definition resolves to a
private address. TRUEPPM_EGRESS_ALLOWLISTED_HOSTS_SSO is the escape hatch (read at
startup, so a change needs a restart). It exempts a host for single sign-on only;
SMTP, integrations and webhooks each have their own list — see Single sign-on.
One encryption key for every stored third-party secret
Section titled “One encryption key for every stored third-party secret”INTEGRATION_ENCRYPTION_KEY is one Fernet key. It encrypts the single sign-on
client secret (SsoProviderPolicy.secret_ciphertext), every user’s stored
external-source credential such as Jira (IntegrationCredential), outgoing webhook
secrets (Webhook.secret_ciphertext), board-automation secrets
(BoardAutomation.secret_ciphertext), and the outbound SMTP password
(password_ciphertext on the notifications SMTP settings). ADR-0187 left open
whether OIDC should have its own key; the code resolved it by reuse, and this
page records that as an accepted risk so it is not rediscovered as a finding.
The consequences are structural. A leak of the key exposes every one of these
together. Rotation is supported without data loss, in two phases (add the new key as a
fallback and finish that rollout, then promote it): INTEGRATION_ENCRYPTION_KEY_FALLBACKS
holds additional keys that a MultiFernet tries for decryption only (writes use the
primary), and manage.py reencrypt_integration_secrets rewrites every stored
ciphertext under the primary (run it after the phase-2 rollout has finished) so a fallback can be dropped. Changing the key with no
fallback still breaks every stored ciphertext and recovery is for an administrator
to re-enter every secret. The operator-facing version of this is in
Secret management.
The Enterprise counterpart (a KMS-backed key) is not yet filed as its own issue. The
nearest existing item is customer-managed encryption keys, trueppm-enterprise#181,
which does not mention this key.
OSS and Enterprise
Section titled “OSS and Enterprise”The dividing line is the same one used everywhere else in TruePPM: log in
via your own identity provider → open-source core; provision, deprovision, and
govern accounts from a directory → Enterprise. Single sign-on — multiple
OIDC providers plus GitHub, configured independently, with auto-created
membership at a single fixed default role — shipped in 0.4 as part of the
open-source core described here. Group-to-role claim mapping, enforced SSO
(disabling local password accounts), SCIM provisioning, and LDAP/AD directory
sync are Enterprise; the two extension seams this architecture exposes for
that boundary — oidc_role_for(claims, policy) and
local_login_allowed(user) — resolve to the open-source default (ignore
claims; always allow local login) unless Enterprise registers an override.
See SSO is not Enterprise for the full
reasoning behind where this line sits.
Where to go next
Section titled “Where to go next”- Single sign-on — configuring a provider, the sign-in experience, and operator-facing security notes.
- RBAC and permission architecture — what happens after a caller is authenticated: the role and object-level checks, and how the WebSocket ticket above hands off into the project-role gate.
- Architecture Decision Records — ADR-0141 (the WebSocket ticket), ADR-0187 (the original bespoke OIDC relying party, since superseded), and ADR-0517 (adopting allauth as a provider registry) are the primary records behind this page.