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.
What exists today
Section titled “What exists today”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.
The contract
Section titled “The contract”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: defaultBind with -i keycloak=KEYCLOAK. The oidc socket job, additive, on
bind/update:
- create each client role on the chosen client if missing
- create each realm group if missing (
/mailcow,/Employee) - assert the named group attributes
- 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.
Client target: this plug’s own client
Section titled “Client target: this plug’s own client”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.
What this sitting will not do
Section titled “What this sitting will not do”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.