Map identity provider groups to Mila roles #651

Open
opened 2026-11-09 17:34:40 +01:00 by simon · 0 comments
Owner

Background

Since #646 the single sign-on sync manages only the Admin role: a user in the admin group (OIDC_ADMIN_GROUP_NAME) becomes Admin, an Admin who is no longer in it becomes "Mitglied", and every other role assigned in Mila stays. Clubs that keep their board, treasurer or office staff in identity provider groups still have to assign those roles by hand in Mila and keep both places in sync.

Proposal

Let an admin map identity provider groups to Mila roles (for example vorstand → board role, kasse → treasurer role), configurable in the settings page and through an environment variable, like the other single sign-on settings. The admin group becomes one entry of this mapping, or stays a separate field (to decide).

Decisions to make

  1. Several mapped groups. A user can be in more than one mapped group. Which role wins: the order of the mapping, the role with the broader permission set, or something else?
  2. Leaving a mapped group. A user who drops out of every mapped group: keep the role (as roles assigned in Mila do today), or fall back to "Mitglied" when the current role is a mapped one? The second needs no extra state for mapped roles, but also removes a role an admin assigned by hand if that role happens to be mapped.
  3. Which role counts as Admin. Today it is the role named "Admin". A custom role with the admin permission set is treated like any other role. Decide whether the mapping and the last-admin guard should go by name or by permission set.
  4. Hint in the user form. Whether and how the role select in the user form says that single sign-on manages the role: a field help under the select, or a note box above it; shown always, or only when the role is mapped or the user signs in through single sign-on.
  5. Manual changes to a mapped role. A role changed in Mila is overwritten on the next sign-in when it is mapped. Lock the select for such users, or only say so?

Keep from #646

  • A token without the configured groups claim changes no role and logs a warning.
  • A change the user resource refuses (for example demoting the last Admin) is logged; the sign-in still succeeds.
  • Roles that no mapping names stay untouched.

Acceptance criteria

  • An admin can configure the mapping in the settings page and through the environment; the settings page shows which mapping is in effect.
  • On sign-in, a user gets the role their groups map to, following the decided precedence; unmapped roles stay.
  • The behavior when a user leaves a mapped group follows decision 2 and is tested.
  • The user form and the settings explain which roles single sign-on manages.
  • Tests cover precedence, leaving a group, a missing claim, an empty claim, and the last-admin refusal.
  • docs/admin-bootstrap-and-oidc-role-sync.md describes the mapping.
## Background Since #646 the single sign-on sync manages only the Admin role: a user in the admin group (`OIDC_ADMIN_GROUP_NAME`) becomes Admin, an Admin who is no longer in it becomes "Mitglied", and every other role assigned in Mila stays. Clubs that keep their board, treasurer or office staff in identity provider groups still have to assign those roles by hand in Mila and keep both places in sync. ## Proposal Let an admin map identity provider groups to Mila roles (for example `vorstand` → board role, `kasse` → treasurer role), configurable in the settings page and through an environment variable, like the other single sign-on settings. The admin group becomes one entry of this mapping, or stays a separate field (to decide). ## Decisions to make 1. **Several mapped groups.** A user can be in more than one mapped group. Which role wins: the order of the mapping, the role with the broader permission set, or something else? 2. **Leaving a mapped group.** A user who drops out of every mapped group: keep the role (as roles assigned in Mila do today), or fall back to "Mitglied" when the current role is a mapped one? The second needs no extra state for mapped roles, but also removes a role an admin assigned by hand if that role happens to be mapped. 3. **Which role counts as Admin.** Today it is the role named "Admin". A custom role with the `admin` permission set is treated like any other role. Decide whether the mapping and the last-admin guard should go by name or by permission set. 4. **Hint in the user form.** Whether and how the role select in the user form says that single sign-on manages the role: a field help under the select, or a note box above it; shown always, or only when the role is mapped or the user signs in through single sign-on. 5. **Manual changes to a mapped role.** A role changed in Mila is overwritten on the next sign-in when it is mapped. Lock the select for such users, or only say so? ## Keep from #646 - A token without the configured groups claim changes no role and logs a warning. - A change the user resource refuses (for example demoting the last Admin) is logged; the sign-in still succeeds. - Roles that no mapping names stay untouched. ## Acceptance criteria - An admin can configure the mapping in the settings page and through the environment; the settings page shows which mapping is in effect. - On sign-in, a user gets the role their groups map to, following the decided precedence; unmapped roles stay. - The behavior when a user leaves a mapped group follows decision 2 and is tested. - The user form and the settings explain which roles single sign-on manages. - Tests cover precedence, leaving a group, a missing claim, an empty claim, and the last-admin refusal. - `docs/admin-bootstrap-and-oidc-role-sync.md` describes the mapping.
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
local-it/mitgliederverwaltung#651
No description provided.