OIDC: map IdP groups claim to archie orgs and roles #60
Notifications
Due Date
No due date set.
Blocks
Reference: sam/archie#60
Reference in new issue
Block a user
OIDC login reads only subject, email and scopes, so roles are granted by hand. Read a configurable groups claim and map groups to org membership and role, re-evaluated at each login. Mapping is edited in the dashboard per org. Done when a user's archie role follows their IdP group membership with no manual grant.
Imported from beads
archie-core-4nryw· GitHub #1794 · type feature · priority P2 · created 2026-10-18archie's PRD is ready -- awaiting your go/no-go.
PRD — OIDC groups claim → archie org membership and role
Issue: sam/archie #60 (imported
archie-core-4nryw, GitHub #1794), type feature, P2.Status: draft for green-light. Epic-sized: ~1,300 hand-written lines across ~20 files plus ~1,000 generated. Proposed as one PRD and two implementation issues.
Problem
OIDC proves who someone is and nothing about what they may do. Verified in the tree:
oidc.Verifier.Verify(internal/infrastructure/oidc/oidc.go) reads exactlysub,client_id,scope,scp,email,email_verified.identity.Credential(internal/domain/identity/credential.go) carriesSubject,Email,Scopes,Expires. Nowhere ininternal/is a groups claim read —grep groupsover*.gohits only log-attr grouping, event-type proposal grouping and a nav description.membershipsrows. The dashboard writes them one at a time:PUT /api/orgs/{id}/members/{identity}(handleOrgMemberSet,internal/webui/orgs.go:213) andPOST /api/orgs/{id}/membersfor someone who has not signed in yet (handleOrgMemberAdd, by provider subject or email placeholder,orgs.go:238).handleCallback(internal/webui/auth.go:184): exchanges the code, re-resolves throughauthenticateBrowser(auth.go:209), then builds the principal (auth.go:217) and opens the local session. Every later request re-verifies the stored ID token (bearerCredential) and resolves only the subject, so no per-request code path can ever see a groups claim.So an IdP group change requires a human to edit each membership, and the two systems drift: the IdP says who belongs, archie keeps the old role until someone notices. Multi-org memberships, human accounts and add-a-member-by-subject already shipped (CHANGELOG 1.53/1.54 region, lines 146 and 175), and the 1.61 stream is current, so IdP-driven roles are the continuation of shipped work, not a tangent.
Proposed solution
At sign-in, read a configurable groups claim from the verified ID token and apply the per-org group→role mapping the operator stored in the dashboard. The sync is the only new writer; the per-request path is untouched.
Shape, in five parts:
identity.AuthenticationSettingsgainsOIDCGroupsClaim string. Empty means no sync (default off: an existing install behaves exactly as today). It flows through the existing path: domain type +Validate(internal/domain/identity/authentication.go),AuthenticationSettingsmessage field 5 (proto/state/v1/account.proto),authentication_settingscolumn (internal/infrastructure/postgres/authentication.godoes inline SQL; new migration), staterpc mapping (internal/infrastructure/staterpc/authentication.go:14,18), dashboard field (ui/src/accounts/AuthenticationPage.vue). Read at edit time by an instance owner with fresh sign-in, like the other OIDC fields (handleAuthenticationSettings,internal/webui/accounts.go:244).identity.Credential.Groups []string; the verifier reads the configured claim and returns it.Verifier/NewVerifier/NewVerifierForAudiencetake the claim name;oidc.NewFlowtakes it too soFlow.Exchange's credential carries groups (internal/infrastructure/oidc/flow.go). Claim shape: array of strings; a non-array or a missing claim yields no groups and a log line, never a failed sign-in.session.Credential.GroupsfromExchangeis what the callback uses — no second verification, and no new I/O.org.GroupMapping{OrgID, Group string, Role Role}with validation: group name trimmed and length-capped, role in{admin, developer, viewer}.owneris refused (see decision 5). Tableorg_group_roles (org_id, group_name, role)keyed(org_id, group_name); new migration0069_…(current max is0068_task_handoff_runs.sql). Read/write throughorg.APIand three newOrgServiceRPCs (ListGroupMappings,SetGroupMapping,RemoveGroupMapping) inproto/state/v1/org.proto,internal/infrastructure/staterpc/orgs.go+orgs_client.go, and dashboard routesGET/PUT/DELETE /api/orgs/{id}/group-mappings. Editor gated onmanage_members—authorize.go'sorgRouteAction(authorize.go:398) maps/api/orgs/{id}/members|agentstomanage_membersand must learn the new segment, plus apageProbesentry (internal/webui/api_capabilities.go:45), a row in theauthorization_surfaces_test.gomatrix, and rows indocs/security/authorization.md.memberships.source text NOT NULL DEFAULT 'manual' CHECK (source IN ('manual','oidc')), shipped in the same migration as the mapping table even though only revocation reads it — otherwise the rows the phase-1 sync creates are indistinguishable from hand grants and can never be revoked.org.Membership/org.MembergainSource,ListMembersreturns it, the members page shows it ("from IdP group" vs manual).ApplyIdentityGroups(groups repeated string), with no target-identity field: the subject is the caller's forwarded principal, so a browser can never ask it to change someone else's roles. Precedent for a UI call that writes against a named identity isBindIdentityPersonalToken(proto/state/v1/account.proto,internal/webui/identities.go:44); here the named identity is the caller itself, which is stronger. It cannot useSetMembership:orgFor(internal/infrastructure/staterpc/orgs.go:99) confines a call to the caller's own org unless the forwarded principal is an instance admin, and the person being granted a role is by definition not yet a member of that org. The store recomputes the desired role from its own mapping rows — never from a caller-supplied role list — applies org-wide rows only, audits each change through the existinginsertAuditValuespath (actor = the person, source =archie-ui, fromaccess.ActorFromContext/SourceFromContext), and returns the changes. Owner grants are unrepresentable, soguardOwners/ErrLastOwner(internal/infrastructure/postgres/owners_guard.go) is never on this path.Call site:
handleCallback, after the identity resolves and befores.Principals.PrincipalFor(internal/webui/auth.go:209-217), so the principal opened into the account session already reflects the new roles. Memberships are re-read per request (postgres PrincipalFor,orgs.go:362), so the grant is effective on the next request without re-login.Decisions, with recommendations
flow.goscopesopenid profile email,audienceparam). Recommend: ID token only.source='oidc', immutable forsource='manual'. The alternative (mapping always wins, overwriting a hand grant and flipping its source) demotes a hand-appointed admin at the next sign-in; reject unless you want "groups are authoritative" as a product promise.ErrSubjectUnbound(internal/domain/identity/authentication.go): a verified subject with no bound identity is refused, and an admin still adds the person by subject or email first. The feature removes the manual role step, not the manual person step, and keeps "OIDC does not automatically link accounts by unverified email or create an administrator" (docs/security/authorization.md) true for two of its three clauses. Recommend: keep as is.alert.KindMembershipGroupSyncFailed, new kind ininternal/domain/alert/alert.go;staterpc.Clientalready implementsalert.Raiserviaalerts_client.go, the UI composition only wires the reader today —wireAlerts,internal/app/archieui/compose.go:266). A failed apply leaves the previous roles in place until the next sign-in; say so in the dashboard copy next to the mapping editor. Recommend: continue and report.owner? No.access.Principal.InstanceAdmin()is "owner of org-sys", so a mapped owner in org-sys is an IdP-driven instance takeover, and it would put the sync on theErrLastOwnerpath. Owner stays a manual grant, guarded as today bymayChangeMembership(internal/webui/orgs.go:393). Recommend: exclude owner from the mapped vocabulary; refuse it inGroupMapping.Validate.Membership.WorkspaceIDandPrincipal.Role(ws)support it, but workspace mappings multiply records, editor states and the "which org does this person belong to" answer (ResolveIdentityOrgtakes the oldest membership). Org-wide only in this work.Phases
Phase 1 — claim, mapping storage and editor, grant-only sync. Safe to ship alone: the sync inserts and adjusts only rows with
source='oidc'; it never removes a role and never lowers one it did not grant. A person who leaves a group keeps the role until phase 2.Phase 2 — revocation. Desired-role computation already exists from phase 1; phase 2 deletes the
source='oidc'rows no group justifies, raises the failure alert, and documents the stale-role window.Phase 3 (deferred, only if a real provider needs it) — userinfo fallback or an extra-scopes setting. Not designed here.
The assessment put the editor in phase 3; it belongs in phase 1 because it is the only way to author the mappings the sync reads, and a setting with no authoring surface is a bug under AGENTS.md.
Files and components affected
Domain —
internal/domain/identity/credential.go(Credential.Groups),authentication.go(OIDCGroupsClaim + Validate),internal/domain/org/org.go(GroupMapping, Source, ErrInvalidGroupMapping),internal/domain/org/store.go(Repository/API additions + a narrowGroupSyncerinterface, theorg.Creatorprecedent),internal/domain/alert/alert.go(one kind).Infrastructure —
internal/infrastructure/oidc/oidc.go(claim read, verifier claim field),flow.go(claim into the exchange's credential),internal/infrastructure/postgres/migrations/0069_*.sql(mappings table, memberships.source),queries/orgs.sql(mapping CRUD, source on ensure/list),postgresdb/*.sql.go(regenerated),postgres/orgs.go(mapping CRUD,ApplyGroups, mapping-aware ensure),postgres/authentication.go(column),internal/infrastructure/staterpc/orgs.go+orgs_client.go+authentication.go.Contracts —
proto/state/v1/org.proto(3 mapping RPCs +ApplyIdentityGroups),proto/state/v1/account.proto(field 5), regeneratedinternal/contracts/state/v1/org*.go,account.pb.go.UI service —
internal/webui/orgs.go(routes, owner-guarded mapping handlers),authorize.go(route→manage_members),api_capabilities.go(page probe),auth.go(callback hook),server.go(syncer + raiser fields),internal/app/archieui/compose.go/run.go(wiring).Dashboard — new
ui/src/org/OrgGroupMappingsPage.vue,ui/src/org/org.ts(types),ui/src/lib/api.ts(calls),ui/src/router/index.ts(child of/org, sectionorg_members),ui/src/lib/nav.ts("People & access"),internal/gateway/dashboard_tools.go(mirrored route table),ui/src/accounts/AuthenticationPage.vue(claim field),ui/src/org/OrgMembersPage.vue(grant source column).Docs — new
docs/prds/oidc-group-mapping.md,docs/security/authorization.md(inventory row + route table rows + the "does not automatically grant membership" sentence),CHANGELOG.md. Note:docs/prds/orgs-and-access.mdis cited by nine comments (proto/state/v1/org.proto,access.proto,types.proto,internal/domain/org/store.go, migration 0013,configuration/defaults.go, the harness PRD) but does not exist — the new PRD is a sibling file, so this adds one more dangling citation unless that gap is closed separately.Acceptance criteria
Phase 1
oidc_groups_claimempty, sign-in and roles behave exactly as today (no sync, no writes, no new rows)./settings/authentication; saving a claim name with OIDC unconfigured is refused with400.developerin org X gives that person an org-widedevelopermembership in X withsource='oidc', visible on/org/members, and the person's next request acts with that role (no manual grant).source='manual'membership is never modified by the sync, even when the mapping disagrees; the members page shows it as manual.oidcrow's role in phase 1 (assert both).owneris rejected byGroupMapping.Validate, byPUT /api/orgs/{id}/group-mappings, and by the RPC (InvalidArgument).403andErrSubjectUnbound; no identity is created.TestHTTPPolicyCannotBeBypassed, are refused anonymously and under an explicit forbid, map tomanage_members, are absent for a caller in another org (orgInPath), and hide the page viapageProbeswhen refused.task check,task proto:generate,task db:generateclean on the committed tree.Phase 2
13. A person whose groups no longer justify an
oidcmembership loses it; the audit row records the old role and a delete.14. A
manualrow in the same org survives the same sign-in unchanged.15. Nothing in the sync path can trip
ErrLastOwner; if it ever could, the refusal leaves the role in place, the sign-in continues and the alert names the org.Explicit non-goals
Userinfo fetching, SAML/LDAP/SCIM, auto-creating identities or linking by email (decision 3), workspace-scoped mappings, group→Cedar-policy or group→tool mapping, mapping
owner, IdP-driven tenants/org creation, group membership for agents/service accounts, syncing outside the browser callback (no sync on bearer-token requests, no background reconciliation job), deleting the manual add-member path, extra OAuth scopes, and any change to how a request is authorised after login.Estimated diff size
orgs.go, authentication)Roughly 15× the AGENTS.md ~100-line threshold, which is why it is an epic with two issues and not one. Phase 1 is ~1,150 of it; phase 2 ~250.
Risks
memberships.sourcelands in phase 2 instead of phase 1, every row phase 1 created is indistinguishable from a hand grant and becomes permanently unrevokable. Ship the column and write the marker in phase 1.-oidc-issuerflags, theaccountOIDCfallback settings,internal/app/archieui/account_oidc.go) has no dashboard setting to carry the claim name; those installs keep today's behaviour unless a matching flag is added. Recommend documenting that, or adding-oidc-groups-claimfor parity.archie-ui, which verifies the token. That is the same trust the UI already has over principal forwarding, but it should be stated in the inventory row.Verified vs not verified
Verified by reading this tree: every path, line anchor and claim above; that
orgForconfinesSetMembership, thatguardOwnersis only reached for org-wide owner changes, that memberships are re-read per request, that migration 0068 is the current max, that the UI route and capability tables exist as described, and thatstaterpc.Clientalready implementsalert.Raiser. Not verified: the P2 priority and whether broken work is queued ahead of this (no tracker access from here — AGENTS.md puts "broken beats new" ahead of new features and I could not check it), and nothing was built or run; this was a read-only pass, so no gate result is claimed.Decide in chat or on the dashboard.