OIDC: map IdP groups claim to archie orgs and roles #60

Open
opened 2026-10-27 13:34:47 +00:00 by sam · 1 comment
Owner

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-18

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-18_
sam added the mediumfeature labels 2026-10-27 13:34:47 +00:00
sam self-assigned this 2026-10-27 13:34:47 +00:00
Author
Owner

archie'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 exactly sub, client_id, scope, scp, email, email_verified. identity.Credential (internal/domain/identity/credential.go) carries Subject, Email, Scopes, Expires. Nowhere in internal/ is a groups claim read — grep groups over *.go hits only log-attr grouping, event-type proposal grouping and a nav description.
  • Roles come only from memberships rows. The dashboard writes them one at a time: PUT /api/orgs/{id}/members/{identity} (handleOrgMemberSet, internal/webui/orgs.go:213) and POST /api/orgs/{id}/members for someone who has not signed in yet (handleOrgMemberAdd, by provider subject or email placeholder, orgs.go:238).
  • The only login moment is handleCallback (internal/webui/auth.go:184): exchanges the code, re-resolves through authenticateBrowser (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:

  1. Claim setting (instance). identity.AuthenticationSettings gains OIDCGroupsClaim 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), AuthenticationSettings message field 5 (proto/state/v1/account.proto), authentication_settings column (internal/infrastructure/postgres/authentication.go does 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).
  2. Groups on the credential. identity.Credential.Groups []string; the verifier reads the configured claim and returns it. Verifier/NewVerifier/NewVerifierForAudience take the claim name; oidc.NewFlow takes it too so Flow.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.Groups from Exchange is what the callback uses — no second verification, and no new I/O.
  3. Mapping record (per org). New org.GroupMapping{OrgID, Group string, Role Role} with validation: group name trimmed and length-capped, role in {admin, developer, viewer}. owner is refused (see decision 5). Table org_group_roles (org_id, group_name, role) keyed (org_id, group_name); new migration 0069_… (current max is 0068_task_handoff_runs.sql). Read/write through org.API and three new OrgService RPCs (ListGroupMappings, SetGroupMapping, RemoveGroupMapping) in proto/state/v1/org.proto, internal/infrastructure/staterpc/orgs.go + orgs_client.go, and dashboard routes GET/PUT/DELETE /api/orgs/{id}/group-mappings. Editor gated on manage_members — authorize.go's orgRouteAction (authorize.go:398) maps /api/orgs/{id}/members|agents to manage_members and must learn the new segment, plus a pageProbes entry (internal/webui/api_capabilities.go:45), a row in the authorization_surfaces_test.go matrix, and rows in docs/security/authorization.md.
  4. Grant source marker. 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.Member gain Source, ListMembers returns it, the members page shows it ("from IdP group" vs manual).
  5. The sync. A dedicated store-side RPC, 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 is BindIdentityPersonalToken (proto/state/v1/account.proto, internal/webui/identities.go:44); here the named identity is the caller itself, which is stronger. It cannot use SetMembership: 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 existing insertAuditValues path (actor = the person, source = archie-ui, from access.ActorFromContext/SourceFromContext), and returns the changes. Owner grants are unrepresentable, so guardOwners/ErrLastOwner (internal/infrastructure/postgres/owners_guard.go) is never on this path.

Call site: handleCallback, after the identity resolves and before s.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

  1. Claim source. Read the ID token only, claim name configurable, provider requirement documented. Userinfo adds an external call and a way to fail a sign-in when the IdP's userinfo is down; the browser flow already keeps only the ID token (flow.go scopes openid profile email, audience param). Recommend: ID token only.
  2. Revocation. Strict for rows the sync owns; manual rows are never touched — not promoted, not demoted, not removed — and the members page shows the source so an operator can see why a mapping is not applying. The assessment's "additive for everything else" is subsumed by this and is simpler to reason about: the sync only ever writes roles it owns. Recommend: strict for source='oidc', immutable for source='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.
  3. Unknown subject. Keep 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.
  4. Sync failure. Sign-in continues. The failure is logged with the identity and the org, and an alert is raised (alert.KindMembershipGroupSyncFailed, new kind in internal/domain/alert/alert.go; staterpc.Client already implements alert.Raiser via alerts_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.
  5. May a mapping grant 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 the ErrLastOwner path. Owner stays a manual grant, guarded as today by mayChangeMembership (internal/webui/orgs.go:393). Recommend: exclude owner from the mapped vocabulary; refuse it in GroupMapping.Validate.
  6. Workspace-scoped mappings: not now. Membership.WorkspaceID and Principal.Role(ws) support it, but workspace mappings multiply records, editor states and the "which org does this person belong to" answer (ResolveIdentityOrg takes 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 narrow GroupSyncer interface, the org.Creator precedent), 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), regenerated internal/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, section org_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.md is 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

  1. With oidc_groups_claim empty, sign-in and roles behave exactly as today (no sync, no writes, no new rows).
  2. Set to a claim the ID token carries as a string array, an instance owner saves it from /settings/authentication; saving a claim name with OIDC unconfigured is refused with 400.
  3. A verified sign-in whose groups include one mapped to developer in org X gives that person an org-wide developer membership in X with source='oidc', visible on /org/members, and the person's next request acts with that role (no manual grant).
  4. Highest role wins when several of a person's groups map into the same org; a group mapped in two orgs grants in both.
  5. An existing source='manual' membership is never modified by the sync, even when the mapping disagrees; the members page shows it as manual.
  6. The sync cannot remove a role in phase 1 and cannot lower an oidc row's role in phase 1 (assert both).
  7. owner is rejected by GroupMapping.Validate, by PUT /api/orgs/{id}/group-mappings, and by the RPC (InvalidArgument).
  8. A non-member of the target org can be granted by the sync; a caller cannot name a different identity — the RPC has no identity field and the test proves the write targets the forwarded principal only.
  9. An unbound verified subject is still refused with 403 and ErrSubjectUnbound; no identity is created.
  10. Missing/non-array claim → no groups, sign-in succeeds, one log line; a store failure → sign-in succeeds, roles unchanged, alert raised, log names identity and org.
  11. New routes appear in TestHTTPPolicyCannotBeBypassed, are refused anonymously and under an explicit forbid, map to manage_members, are absent for a caller in another org (orgInPath), and hide the page via pageProbes when refused.
  12. task check, task proto:generate, task db:generate clean on the committed tree.

Phase 2
13. A person whose groups no longer justify an oidc membership loses it; the audit row records the old role and a delete.
14. A manual row 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

Part Hand-written
Domain (identity, org, alert) ~120
OIDC verifier + flow ~80
Postgres (migration, queries, orgs.go, authentication) ~250
staterpc (server + client + settings mapping) ~170
webui (routes, guards, callback hook, authz mapping, wiring) ~200
UI (new page, api, types, router, nav, members column, settings field) ~290
Tests (claim parsing, mapping validation, apply rules, HTTP matrix/guards, RPC target) ~320
Docs + CHANGELOG ~40
Total ~1,470 plus ~1,000 regenerated protobuf/sqlc lines

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

  • Sequencing trap, called out because it is easy to get wrong: if memberships.source lands 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.
  • Provider coverage: groups must be in the ID token. Okta/Azure/Keycloak each need client-side claim configuration; the docs must say so or the feature looks broken when the claim is absent.
  • Env-configured OIDC (-oidc-issuer flags, the accountOIDC fallback 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-claim for parity.
  • Trust: the store cannot verify the group list; it trusts 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 orgFor confines SetMembership, that guardOwners is 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 that staterpc.Client already implements alert.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.

**archie'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 exactly `sub`, `client_id`, `scope`, `scp`, `email`, `email_verified`. `identity.Credential` (`internal/domain/identity/credential.go`) carries `Subject`, `Email`, `Scopes`, `Expires`. Nowhere in `internal/` is a groups claim read — `grep groups` over `*.go` hits only log-attr grouping, event-type proposal grouping and a nav description. - Roles come only from `memberships` rows. The dashboard writes them one at a time: `PUT /api/orgs/{id}/members/{identity}` (`handleOrgMemberSet`, `internal/webui/orgs.go:213`) and `POST /api/orgs/{id}/members` for someone who has not signed in yet (`handleOrgMemberAdd`, by provider subject or email placeholder, `orgs.go:238`). - The only login moment is `handleCallback` (`internal/webui/auth.go:184`): exchanges the code, re-resolves through `authenticateBrowser` (`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: 1. **Claim setting (instance).** `identity.AuthenticationSettings` gains `OIDCGroupsClaim 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`), `AuthenticationSettings` message field 5 (`proto/state/v1/account.proto`), `authentication_settings` column (`internal/infrastructure/postgres/authentication.go` does 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`). 2. **Groups on the credential.** `identity.Credential.Groups []string`; the verifier reads the configured claim and returns it. `Verifier`/`NewVerifier`/`NewVerifierForAudience` take the claim name; `oidc.NewFlow` takes it too so `Flow.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.Groups` from `Exchange` is what the callback uses — no second verification, and no new I/O. 3. **Mapping record (per org).** New `org.GroupMapping{OrgID, Group string, Role Role}` with validation: group name trimmed and length-capped, role in `{admin, developer, viewer}`. **`owner` is refused** (see decision 5). Table `org_group_roles (org_id, group_name, role)` keyed `(org_id, group_name)`; new migration `0069_…` (current max is `0068_task_handoff_runs.sql`). Read/write through `org.API` and three new `OrgService` RPCs (`ListGroupMappings`, `SetGroupMapping`, `RemoveGroupMapping`) in `proto/state/v1/org.proto`, `internal/infrastructure/staterpc/orgs.go` + `orgs_client.go`, and dashboard routes `GET/PUT/DELETE /api/orgs/{id}/group-mappings`. Editor gated on `manage_members` — `authorize.go`'s `orgRouteAction` (`authorize.go:398`) maps `/api/orgs/{id}/members|agents` to `manage_members` and must learn the new segment, plus a `pageProbes` entry (`internal/webui/api_capabilities.go:45`), a row in the `authorization_surfaces_test.go` matrix, and rows in `docs/security/authorization.md`. 4. **Grant source marker.** `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.Member` gain `Source`, `ListMembers` returns it, the members page shows it ("from IdP group" vs manual). 5. **The sync.** A dedicated store-side RPC, `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 is `BindIdentityPersonalToken` (`proto/state/v1/account.proto`, `internal/webui/identities.go:44`); here the named identity is the caller itself, which is stronger. It cannot use `SetMembership`: `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 existing `insertAuditValues` path (actor = the person, source = `archie-ui`, from `access.ActorFromContext`/`SourceFromContext`), and returns the changes. Owner grants are unrepresentable, so `guardOwners`/`ErrLastOwner` (`internal/infrastructure/postgres/owners_guard.go`) is never on this path. Call site: `handleCallback`, after the identity resolves and before `s.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 1. **Claim source.** Read the ID token only, claim name configurable, provider requirement documented. Userinfo adds an external call and a way to fail a sign-in when the IdP's userinfo is down; the browser flow already keeps only the ID token (`flow.go` scopes `openid profile email`, `audience` param). **Recommend: ID token only.** 2. **Revocation.** Strict for rows the sync owns; **manual rows are never touched** — not promoted, not demoted, not removed — and the members page shows the source so an operator can see why a mapping is not applying. The assessment's "additive for everything else" is subsumed by this and is simpler to reason about: the sync only ever writes roles it owns. **Recommend: strict for `source='oidc'`, immutable for `source='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. 3. **Unknown subject.** Keep `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.** 4. **Sync failure.** Sign-in continues. The failure is logged with the identity and the org, and an alert is raised (`alert.KindMembershipGroupSyncFailed`, new kind in `internal/domain/alert/alert.go`; `staterpc.Client` already implements `alert.Raiser` via `alerts_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.** 5. **May a mapping grant `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 the `ErrLastOwner` path. Owner stays a manual grant, guarded as today by `mayChangeMembership` (`internal/webui/orgs.go:393`). **Recommend: exclude owner from the mapped vocabulary; refuse it in `GroupMapping.Validate`.** 6. **Workspace-scoped mappings: not now.** `Membership.WorkspaceID` and `Principal.Role(ws)` support it, but workspace mappings multiply records, editor states and the "which org does this person belong to" answer (`ResolveIdentityOrg` takes 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 narrow `GroupSyncer` interface, the `org.Creator` precedent), `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), regenerated `internal/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`, section `org_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.md` is 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** 1. With `oidc_groups_claim` empty, sign-in and roles behave exactly as today (no sync, no writes, no new rows). 2. Set to a claim the ID token carries as a string array, an instance owner saves it from `/settings/authentication`; saving a claim name with OIDC unconfigured is refused with `400`. 3. A verified sign-in whose groups include one mapped to `developer` in org X gives that person an org-wide `developer` membership in X with `source='oidc'`, visible on `/org/members`, and the person's next request acts with that role (no manual grant). 4. Highest role wins when several of a person's groups map into the same org; a group mapped in two orgs grants in both. 5. An existing `source='manual'` membership is never modified by the sync, even when the mapping disagrees; the members page shows it as manual. 6. The sync cannot remove a role in phase 1 and cannot lower an `oidc` row's role in phase 1 (assert both). 7. `owner` is rejected by `GroupMapping.Validate`, by `PUT /api/orgs/{id}/group-mappings`, and by the RPC (`InvalidArgument`). 8. A non-member of the target org can be granted by the sync; a caller cannot name a different identity — the RPC has no identity field and the test proves the write targets the forwarded principal only. 9. An unbound verified subject is still refused with `403` and `ErrSubjectUnbound`; no identity is created. 10. Missing/non-array claim → no groups, sign-in succeeds, one log line; a store failure → sign-in succeeds, roles unchanged, alert raised, log names identity and org. 11. New routes appear in `TestHTTPPolicyCannotBeBypassed`, are refused anonymously and under an explicit forbid, map to `manage_members`, are absent for a caller in another org (`orgInPath`), and hide the page via `pageProbes` when refused. 12. `task check`, `task proto:generate`, `task db:generate` clean on the committed tree. **Phase 2** 13. A person whose groups no longer justify an `oidc` membership loses it; the audit row records the old role and a delete. 14. A `manual` row 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 | Part | Hand-written | |---|---| | Domain (identity, org, alert) | ~120 | | OIDC verifier + flow | ~80 | | Postgres (migration, queries, `orgs.go`, authentication) | ~250 | | staterpc (server + client + settings mapping) | ~170 | | webui (routes, guards, callback hook, authz mapping, wiring) | ~200 | | UI (new page, api, types, router, nav, members column, settings field) | ~290 | | Tests (claim parsing, mapping validation, apply rules, HTTP matrix/guards, RPC target) | ~320 | | Docs + CHANGELOG | ~40 | | **Total** | **~1,470** plus ~1,000 regenerated protobuf/sqlc lines | 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 - **Sequencing trap, called out because it is easy to get wrong:** if `memberships.source` lands 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. - **Provider coverage:** groups must be in the ID token. Okta/Azure/Keycloak each need client-side claim configuration; the docs must say so or the feature looks broken when the claim is absent. - **Env-configured OIDC** (`-oidc-issuer` flags, the `accountOIDC` fallback 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-claim` for parity. - **Trust:** the store cannot verify the group list; it trusts `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 `orgFor` confines `SetMembership`, that `guardOwners` is 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 that `staterpc.Client` already implements `alert.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._
sam added a new dependency 2026-11-14 14:45:09 +00:00
sam added the deferred label 2026-11-15 17:26:26 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#60