OIDC group roles and Keycloak directory sync

[dniasoff]

Problem

With a generic OIDC issuer, access to a private installation is a hand-maintained member list: an administrator admits each person by email, assigns their role in Artifact Server, and must remember to deactivate leavers. Teams that already manage access with IdP groups (Keycloak, Authentik, Zitadel and others put a groups claim in tokens) cannot reuse those groups. People cannot be seen, shared with, or assigned work until each one has been admitted by hand.

Change

Two opt-in features. With none of the new settings set, behaviour and the rendered chart are unchanged, except that every chart pod now sets enableServiceLinks: false (see below).

1. Group roles at sign-in (commit "Admit OIDC members and set their roles from issuer groups")

• Settings: ARTIFACT_SERVER_OIDC_MEMBER_GROUPS, ARTIFACT_SERVER_OIDC_ADMINISTRATOR_GROUPS (comma lists, exact match) and ARTIFACT_SERVER_OIDC_GROUPS_CLAIM (default groups). Chart values: identity.oidcMemberGroups, identity.oidcAdministratorGroups, identity.oidcGroupsClaim.
• How the role is decided:
  • an administrator group gives administrator; a member group gives member;
  • anyone in neither is denied, and any existing membership is deactivated.
• When it applies: at browser sign-in and on every OIDC MCP access token, so a removal takes effect on the person's next call. When the policy is on, the bootstrap-email rule is not used.
• Edge cases:
  • someone who rejoins a group is reactivated on their existing record;
  • a last administrator who loses their groups is demoted before being deactivated;
  • a groups claim that is not a list of strings is a provider failure.

2. Directory sync, so members exist before they first sign in (commit "Sync OIDC members from a Keycloak directory before they sign in")

• artifactserver maintenance sync-directory --once reads the configured groups from the Keycloak admin REST API (<base>/admin/realms/<realm>, derived from the issuer). It authenticates with a client-credentials service account that needs only realm-management view-users + query-groups.
• It applies the same domain rules directly through the identity repository (no HTTP admin API, no API key): admit, reactivate, change role, and deactivate members who are no longer in any group.
• Every configured group is read in full before anything is written. An unknown group, a token or HTTP error, or zero eligible users aborts the run with nothing changed.
• It prints one JSON summary line.
• Settings: ARTIFACT_SERVER_OIDC_DIRECTORY_PROVIDER=keycloak, ARTIFACT_SERVER_OIDC_DIRECTORY_CLIENT_ID, and ARTIFACT_SERVER_OIDC_DIRECTORY_CLIENT_SECRET[_FILE].
• Chart: identity.oidcDirectoryClientId plus secret.keys.oidcDirectoryClientSecret enable a <release>-sync-directory CronJob (directorySync.schedule, default every 10 minutes), which is counted in postgresConnectionBudget.

Also in the chart: enableServiceLinks: false on every pod. With the release named artifact-server, Kubernetes service links inject ARTIFACT_SERVER_PORT=tcp://<ip>:80, which the CLI reads as its port, so the cleanup CronJob failed on every run. This is the one rendering change with no new values set.

Tests

• Unit tests for role decisions and config parsing.
• New conformance tests:
  • browser sign-in group roles;
  • MCP group roles: member, admin, denied and deactivated, promotion and demotion on a later token, malformed claim, policy off;
  • directory sync against a stub Keycloak over real HTTP: pagination, admin beats member, both directions of role change, reactivation, leaver, every abort-before-write case, disabled and unverified users, and a pre-created member binding at first sign-in.
• CLI tests and Helm verify cases.
• Locally: lint and typecheck clean; the full suite 356/356; the Cloudflare suite 37/37; the Postgres external-storage integration 19/19, including the compiled CLI sync against real Postgres; conformance ID check valid.

Live verification: we run this branch, as an orvex fork build, against Keycloak 26.5 with CNPG Postgres. The scheduled sync admitted two not-yet-signed-in people with the correct roles. A probe user was then admitted, reactivated, promoted, demoted and deactivated as its Keycloak group memberships changed.

Deployment effects

There are no migrations. The new Postgres access is only UPDATE installation_members SET role=…, through the new setMemberRole repository method, which is also implemented for SQLite and D1.

Depends on nothing else. #94 (OAuth bearer on upload PUT) is independent.