#217: map IdP groups and roles onto the permission model #285

Merged

fable-5 merged 1 commits from issue-217-claim-mapping into main 2026-07-31 13:36:02 +02:00

Conversation 0 Commits 1 Files Changed 14 +582 -24

fable-5 commented 2026-07-31 13:09:55 +02:00

Collaborator

Copy Link

Declarative idpMapping.rules turn ID-token claims into pond roles and the site-admin flag on every OIDC login. Mapped grants go through the SAME GrantsService path (cache invalidation + collab access notify asserted by test), never raw rows. Ownership via role_grants.origin and users.is_site_admin_managed: the mapping only touches what it owns - manual wins, always. Claim removal revokes on next login; every change audited with origin idp_mapping; unknown slugs / last-admin protection log-and-skip (never a login lockout). Documented in permissions.md, ADR 0021, data-model.md, hardening guide. Stacked on #216. Refs #217

Declarative idpMapping.rules turn ID-token claims into pond roles and the site-admin flag on every OIDC login. Mapped grants go through the SAME GrantsService path (cache invalidation + collab access notify asserted by test), never raw rows. Ownership via role_grants.origin and users.is_site_admin_managed: the mapping only touches what it owns - manual wins, always. Claim removal revokes on next login; every change audited with origin idp_mapping; unknown slugs / last-admin protection log-and-skip (never a login lockout). Documented in permissions.md, ADR 0021, data-model.md, hardening guide. Stacked on #216. Refs #217

fable-5 added 4 commits 2026-07-31 13:09:55 +02:00

#214: OIDC Authorization Code with PKCE, Keycloak as reference IdP ... 5796b7a5dd

External authentication (ADR 0021) built on jose (#188's vetted library)
plus fetch — no new dependency enters the supply chain for a security
base function. Discovery-configured; ID tokens validate against the
IdP's JWKS under an explicit RS256/ES256 allowlist with issuer,
audience, expiry and nonce binding. State, nonce and the PKCE verifier
travel in a signed HttpOnly Lax cookie keyed by a dedicated HKDF
purpose (oidc-state, ADR 0020).

Deploy-level configuration (OIDC_ISSUER/CLIENT_ID/CLIENT_SECRET/SCOPES/
PROVIDER_LABEL): who authenticates users is a platform decision. The
login page discovers the provider via GET /auth/methods and renders the
SSO button (i18n de+en).

Identities use the existing slot (provider oidc:<issuer>, subject from
the token). First login creates the account just-in-time — ACTIVE and
mail-verified only when the IdP asserts a verified address. An existing
local account is NEVER adopted silently by e-mail (account-takeover
path): login refuses with oidc_link_required and the owner links
explicitly via GET /auth/oidc/link (audited auth.identity_linked,
catalogue v1.3). Sessions come from the one existing session service.

Tests run the full flow against a protocol-faithful fake IdP: PKCE
verifier at the token endpoint, JIT creation incl. personal pond,
invalid state/nonce/signature/issuer/audience/expiry each rejected, the
linking refusal and the explicit link flow. Verified end-to-end against
a real Keycloak 26.0 (repeatable procedure documented in security.md
§External authentication).

Refs #214.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#215: trusted reverse-proxy header / mTLS client-certificate path ... 4c7f001cab

For perimeters that authenticate before the application (ADR 0021 §4).
Off unless BOTH AUTH_PROXY_HEADER and AUTH_PROXY_TRUSTED_PEERS are set —
nothing about the header is guessed. The peer check runs against the TCP
peer address only (a forwarded header is attacker-influenced): a request
carrying the header from any other peer is rejected outright and audited
as auth.proxy_rejected (catalogue v1.4) — that is a spoof attempt, not a
misconfiguration — even when a valid session cookie rides along. From a
trusted peer the header IS the identity; a session cookie never
escalates beyond it; with the feature off the header is inert.

Mapping is explicit (AUTH_PROXY_MAP: username or e-mail); deliberately
no just-in-time creation — the header carries no verified address. The
mTLS variant (AUTH_PROXY_MODE=mtls-dn) maps the configured attribute
(default CN) out of the certificate subject DN the TLS terminator
forwards, under the same peer rules. Session-less proxy requests key the
read trail per user (user:<id>).

The trust boundary is stated in security.md (the section an assessor
reads closest), the VS-NfD security documentation and the hardening
guide's deploy table. Tests cover all four decisions: off = inert,
trusted peer authenticates (username and DN mapping), untrusted peer
rejected + audited, no escalation past a session cookie.

Refs #215.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#216: hard AUTH_LOCAL_ENABLED switch over every local credential flow ... 13f0311d8e

The deploy-level realization of auth.local.enabled (ADR 0021): FALSE
answers 404 on every local credential flow — login, signup, e-mail
verification, resend, password forgot/reset/change — enforced centrally
in the auth guard via the @LocalCredentialFlow() marker before any
session or CSRF logic runs. Deploy-level on purpose: a compromised Site
Admin cannot reopen the local path, so the runtime-flip residual risk
from ADR 0021 does not materialize (R-02 closed in the risk list).

An enumeration fence fails when an auth route is neither marked nor on
the reviewed allowlist, so a new credential flow cannot ship unswitched.
Stated decisions, each tested: sessions/logout keep working for
externally authenticated users; PAT and feed-token issuance stays
available (API authorization under its own switches, not interactive
sign-in). Bootstrap: complete setup (or SETUP_ADMIN_* pre-seed) before
flipping; the api warns at boot when local auth is off with neither OIDC
nor proxy auth configured. GET /auth/methods reports local:false and the
login page hides the local form and credential links.

Hardening guide: the planned auth.local.enabled row moves from 1.3 into
the live deploy table with the bootstrap ordering, and the verification
checklist gains the login-404 probe.

Refs #216.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#217: map IdP groups and roles onto the permission model ... 6aac785841

Declarative instance setting idpMapping.rules turns ID-token claims into
pond roles and the site-admin flag on every OIDC login — configuration,
not code. Mapped grants travel through the SAME GrantsService path as
manual ones (permission cache invalidated, collab access notify fires so
live sessions revalidate — asserted by test), never raw rows.

Ownership makes precedence explicit: role_grants.origin marks mapped
rows, users.is_site_admin_managed marks a mapping-set admin flag. The
mapping only creates and revokes what it owns — manual wins: hand-made
grants and hand-promoted admins are never revoked by a missing claim (a
manual toggle clears the marker and takes ownership). Removal of a claim
revokes the mapped grant and the managed flag on the next login. Every
mapping-driven change is audited with origin idp_mapping.

Failure containment: unknown pond slugs and the last-Pond-Admin
protection log-and-skip — a mapping problem must never become a login
lockout. Tests drive real OIDC logins against the fake IdP with group
claims: grant + working access, revocation incl. notify, manual-wins,
managed site-admin promote/demote/hands-off.

Documented in permissions.md (own section), ADR 0021, data-model.md and
the hardening guide (care rule: same PR).

Refs #217.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

fable-5 merged commit 6aac785841 into main 2026-07-31 13:36:02 +02:00

fable-5 referenced this pull request 2026-07-31 13:47:16 +02:00

[VS-NfD] Map IdP groups and roles onto the permission model #217

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

  

area:docs

  

area:export

  

area:ops

  

area:storage

  

area:supply-chain

  

auth

Authentication, permissions, quotas

  

backend

API server (apps/api)

  

blocked

Blocked on external dependency/infrastructure

  

collab

Collaboration server (apps/collab)

  

deployment

Docker, CI/CD, hosting

  

docs

Documentation

  

effort:L

  

effort:M

  

effort:S

  

frontend

SPA (apps/web)

  

plugins

Plugin system and SDK

  

qa

Tests, fixtures, e2e

  

vs-nfd

  

vs-nfd:blocker

No Label

area:auth

area:docs

area:export

area:ops

area:storage

area:supply-chain

auth

backend

blocked

collab

deployment

docs

effort:L

effort:M

effort:S

frontend

plugins

qa

vs-nfd

vs-nfd:blocker

Milestone

Clear milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

No Assignees

1 Participants

Notifications

Subscribe

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: stwaidele/dorfteich#285

No description provided.