Othala
Architecture
Six diagrams: who is inside the trust boundary, how a login becomes a token, how an app with no OIDC gets an answer anyway, and what happens on sign-out.
Then how the first credential gets in the door, and how one group becomes two different grants. Each diagram carries the what in its caption; the prose beside it is the why.
One trust domain
Everything downstream of a login trusts whatever token or session Othala hands it, so the first question is what can reach the two Ory admin APIs at all. The answer is one process. The portal runs a public listener the edge reaches and a second, internal-network admin listener the edge never touches, so every admin-API caller stays inside one trust domain instead of becoming a service-to-service authorization problem of its own.
ARCHITECTURE.md § Trust boundary has the enforcement; the Hardening guide's Admin-API isolation section walks the control end to end.
How a login becomes a token
A relying party, here Grafana, redirects the browser to Hydra. Hydra ships no login UI of its own, so it opens a login challenge on the portal, and with no session yet the portal sends the browser to Kratos.
Kratos runs the passkey ceremony, sets the session cookie and resumes the authorize request. A remembered subject skips the passkey but never the gate: Hydra's memory of a past login is never trusted without a live Kratos session behind it.
At consent the portal gates again, then maps groups to the claims the token carries. Hydra hands Grafana a code to exchange server-side. The Per-app OIDC guide walks one relying party through it; ARCHITECTURE.md § The OIDC path has the sequencing.
The apps that speak no OIDC
Not every app in the house can run an OAuth2 redirect, so the edge asks a question instead. Before any proxying, it sends a sub-request to the portal carrying the session cookie and a group name that the edge's own config sets, never an inbound header.
The portal verifies the session, then re-resolves the identity through the Kratos admin API, because group metadata is not in whoami. The gate fails closed at every step: an inactive identity, a non-canonical stored group or a missing group each refuse.
The answer is a status, and each status means one thing. 401 is the only denial an edge may turn into a login redirect. 503 means Kratos never answered; folding it into 403 would turn an outage into an endless bounce. ARCHITECTURE.md § The forward-auth request path has the contract.
What actually happens on sign-out
Hydra and Kratos each remember something about a session. When Hydra says it remembers a subject, the login handler still checks for a live Kratos session belonging to that same identity before honouring the skip. No match means signing in again.
Revoking a subject is one in-process fan-out that cuts the Kratos sessions and both of Hydra's remembered sessions in a fixed order, whatever the trigger. It stops sessions, not credentials, so a lost-device eviction deletes the credential first; theHardening guide has that procedure.
How the first credential gets in the door
There is no self-service registration. An admin creates each identity through the admin API with no credentials block at all, then mints a recovery link and a one-time code together and hands them over on a conversation that already exists with that person.
The person redeems the code in their own browser, which is where a password and a passkey are first set. Neither ever leaves it.
One branch refuses outright. When the target carries the admin marker, recovery is refused before Kratos is ever asked, so an admin's own recovery stays at the console.
One group gets you in; the other decides what you can do
Every manifest binds a group twice, and the two bindings do different jobs on purpose. presentation.access is entry: hold it and the gate admits you.consent.group_role_map is role: it elevates someone already admitted and grants nothing on its own, so holding only an app's admin group gets a person nowhere.
Keeping the two questions on two bindings is what makes an admin group safe to have at all. The Per-app OIDCguide has the manifest shape; ARCHITECTURE.md § The access model has the resolution order.
That is the shape of it end to end. ARCHITECTURE.md has the rest of the reasoning, DECISIONS.md has the rulings no change may reverse, and the repositoryhas the code and the tests these diagrams are drawn from.