Skip to content
SHC Docs

oidc plug groups (realm) and roles (client): Mailcow / Employee

Status: CATALOG DEFAULT SHIPPED. No socket job, no Keycloak write, no shc update mailcow, no mailbox-reconciler apply. SHC-292.

Owner sitting 2026-08-25: stamp mailcow_template=default on Employee (and any other group that should get mail). Skip a nested /mailcow group. The plug should also be able to mint client roles, not realm roles, and to create global groups and wire them.

Client-target question closed (2026-08-25 sitting, no later Clay comment otherwise): roles always land on this app’s client (clientId: mailcow). Do not name another client.


apps/flagship/mailcow/oidc.plug.yaml already binds with -i keycloak= (sole-plug fallback for -i oidc=). On bind it mints the OIDC client, writes Mailcow’s identity-provider row (authsource=keycloak), and maps the user attribute mailcow_template onto the claim Mailcow actually reads. It does not create a Keycloak group and does not put any attribute on one.

ce/builtin/keycloak/oidc.socket.yaml already has client, redirects, groupsClaim (group names in the token), serviceAccount, serviceAccountRoles (realm-management client roles on the service account), and serviceAccountRealmRoles (realm roles for that same service account). There is no “ensure this realm group + attributes” field. Paperless’s ensure-sso-groups creates Django groups, not Keycloak ones.

mailbox-reconciler still keys --var groupPath=/mail-users (empty = every enabled realm user). Membership is direct only: Keycloak’s GET /admin/realms/{realm}/groups/{id}/members does not walk subgroups.

A group attribute does not appear on the user. Mailcow’s UI mapper and the IMAP mailpassword door both read attributes.mailcow_template on the user record (oidc.plug.yaml around the ATTRIBUTE: mailcow_template job). This pin has no group-attribute → claim mapper, only group names. So the group is the source of truth, and something still has to copy the value onto members. mailbox-reconciler already walks groups; that is the natural writer. Same key, value default.

docs/decisions/2026-08-04-mailcow-template-claim.md stays the mechanism ruling for the user claim. This page does not reopen §8.


groups and roles are reusable Keycloak oidc-plug fields, not a Mailcow-only helper. groupsClaim stays what it is: the token claim of group names.

roles:
mailbox-user:
mailbox-admin:
groups:
mailcow:
mailcow_template: default
roles:
- mailbox-user
Employee:
mailcow_template: default

Bind with -i keycloak=KEYCLOAK. The oidc socket job, additive, on bind/update:

  1. create each client role on the chosen client if missing
  2. create each realm group if missing (/mailcow, /Employee)
  3. assert the named group attributes
  4. map the named client roles onto the group

It does not delete roles, groups, or mappings it did not name. It does not create realm roles (serviceAccountRealmRoles already covers that path and stays separate). Employee is not nested under mailcow.

Mail entitlement is any Keycloak group that carries mailcow_template. mailbox-reconciler then keys off that attribute and drops --var groupPath. The same value is copied onto member users so Mailcow’s existing doors still see attributes.mailcow_template.

NetBird / GitLab / anyone else with an oidc plug can declare their own groups: the same way.


Clay: client roles only; global groups yes.

Closed 2026-08-25: roles land on this plug’s own client (clientId: mailcow, or NetBird’s, etc.). That matches how create-oidc-client already owns one client per bind, and it keeps a Mailcow group mapping from writing roles onto realm-management or onto someone else’s client by accident.

Mailcow’s catalog default now ships that map on apps/flagship/mailcow/oidc.plug.yaml. It is not applied.

The other shape, if Clay later wants it: an optional per-role clientId: (or a group-level roleClient:) naming a different client in the same realm. Use that only if an entitlement on Employee has to grant a role that already lives on another client (for example a shared account console role). Do not invent that field until he says so. The job must still refuse realm roles and refuse realm-management manage-* beyond what serviceAccountRoles already allowlists.


No Keycloak POST /groups. No role create. No attribute stamp on live Employee. No mailbox-reconciler groupPath change on corp. No tofu. The apply is a later ce + mailcow + mailbox-reconciler lane.