ADR-010: Roles from Entra ID groups at every sign-in

Status: accepted · Date: 8 April 2024 · Decided by: Marek Nowak, Rafael Duarte

Context

Clients on single sign-on want roles to follow their own directory: when someone joins the "Depot managers" group in Entra ID, they should hold the role in ACME without an administrator doing it twice. When they leave the group, the role should go. Administrators also give roles in the portal by hand, and those must not be wiped by a sign-in.

Decision

• Each client maps Entra ID groups to roles (GroupRoleMap). The groups arrive inside the SAML sign-in as claims.
• At every sign-in, AssignRolesFromClaims removes the role assignments it made from groups last time and makes them again from today's groups.
• Every assignment records its source: saml or portal. Sign-in only touches saml assignments. Assignments made in the portal are left alone.

We considered reading groups from Microsoft's directory API on a schedule. It needs extra permissions in each client's tenant, which their IT teams refuse more often than not.

Consequences

• A group change in Entra ID reaches ACME at the person's next sign-in, not before. For depot staff that is usually the next shift.
• Group names are the client's own. Some name groups per depot, some by job only, so a group can't always tell us the depot.
• Anything we add to a role assignment must survive the next sign-in. Since assignments made in the portal are untouched, data kept on them is safe.

Updates

• 29 September 2025: applies to any SAML provider that sends groups. Okta is not tested yet.