SAML Auto-Approval and Role Mapping

SAML Auto-Approval and Role Mapping (V8.3.3+)

By default an SSO user is created unapproved with no roles, and an administrator approves them and assigns roles by hand in Users. From V8.3.3 two optional settings under Settings › SAML2 / SSO Setup remove that manual step for SAML 2.0 logins:

Auto-approve SSO users approves a new account on its first successful SAML login.
Role mapping reads a group attribute from the SAML assertion on every login and assigns the matching rConfig roles.

Both apply to the generic SAML2 and Shibboleth providers only. Microsoft, Okta and Google OAuth logins keep the manual approval and role assignment workflow.

Prerequisites

SAML 2.0 or Shibboleth login already working, as described in SSO with SAML or SSO with Shibboleth. The settings page shows the environment connection status (SAML2_ENABLED, metadata, SP certificate and key) and is inert until a SAML provider is configured.
An account with the admin role. Viewing the page requires the Setting View permission, saving requires Setting Update.
Your IdP releases a group or role attribute in the assertion (for example memberOf, groups, or the ADFS claim http://schemas.microsoft.com/ws/2008/06/identity/claims/role).

Auto-approve SSO users

Turn on Auto-approve SSO users and save. The next new SAML or Shibboleth user is created with SSO Approved already on and lands on the dashboard after their first login (provided role mapping, if enabled, granted them a role).

Rules:

Approval is granted only when the account is created. Existing unapproved accounts stay unapproved until an administrator toggles them.
An administrator can still revoke approval in Users, and it stays revoked. Auto-approve never re-approves an account.
Each auto-approval is written to the Application Log (auto-approved on first login).

Auto-approve on its own does not assign roles. Without role mapping the approved user logs in with no roles and needs one assigned in Users.

Role mapping

Role mapping is enabled by entering a Role attribute. Leaving it blank disables mapping and rConfig keeps assigning roles manually.

Settings

Setting	Meaning
Role attribute	Name or friendly name of the assertion attribute that carries the user’s groups. Matched case-insensitively. Every value of a multi-valued attribute is read.
Match mode	How each raw group value is reduced before it is compared to roles. See below.
Pattern	Regular expression mode only. One capture group, no delimiters, case-insensitive, up to 255 characters.

Match modes

Mode	Use when your IdP sends	Reduced value
Exact value	Plain group names or object IDs, for example `NetOps` or `7f1c2d3e-…-00000000abcd`	The value as sent, trimmed
Group DN (Active Directory)	Distinguished names such as `CN=NetOps,OU=Groups,DC=example,DC=com`	The `CN` component only (`NetOps`). Escaped commas and hex escapes are handled; values with no `CN` are ignored
Regular expression	Prefixed or wrapped names, for example `rconfig-NetOps` or `app/rconfig/NetOps`	The first capture group of your pattern, for example `^rconfig-(.+)$` gives `NetOps`. Values that do not match are ignored

How roles are resolved

On every SAML login, after the assertion is validated:

All values of the role attribute are read from the assertion.
Each value is reduced according to the match mode.
Each reduced value is compared, case-insensitively, against every active role:
- If the role has one or more SSO group values (set in Settings › RBAC), the reduced value must equal one of them.
- If the role has no SSO group, the reduced value is slugified (lowercased, spaces and underscores become hyphens) and compared to the role’s ident. Net_Ops, NET-OPS and net ops all match a role whose ident is net-ops.
The user’s roles are replaced with every role that matched. One value can grant one role; several values can grant several roles.
If nothing matched, the user is redirected back to the login page with Your account has no rConfig role assigned by your identity provider and their existing roles are removed. The user record is kept.
If the attribute is missing from the assertion, the login is refused the same way and existing roles are removed.

Points that follow from this:

The IdP wins. Adding or removing a group at the IdP adds or removes the role at the next login. Roles added through Change Role in Users are overwritten at the next login.
Inactive roles never match, even if their SSO group or ident would.
A role’s SSO group takes precedence over its ident. Once you set an SSO group on a role, a group value equal to the role’s ident no longer matches it.
Refusal comes before the approval check. A user with no matching role is refused even if they are approved. A user with a matching role but no approval still sees the “not approved” message until approved or auto-approved.
Cached permissions are cleared when roles change, so the new role set applies from that login.

Setting a role’s SSO group

Each role has an optional SSO group list, edited in Settings › RBAC when creating or editing the role. Use it when the value your IdP sends does not equal the role’s ident, typically an Active Directory group name or an object ID.

Up to 20 values per role, each up to 255 characters. Type a value and press Enter to add it.
Values are compared case-insensitively and must be unique across active roles. Saving a role whose SSO group is already used by another active role, or which would match another role’s ident, is rejected with the conflicting role named.
The role ident is derived from the role name when the role is created (Network Operations becomes network-operations) and never changes afterwards, so renaming a role does not break mapping.

The Active roles table on the SAML2 settings page lists every active role and the value it matches on (its SSO groups, or its ident when none are set).

Test a value before saving

Paste one raw group value, exactly as your IdP sends it, into Test a value and press Enter. rConfig reduces it with the match mode and pattern currently in the form (saved or not) and reports the reduced value and the role it would grant, or that no active role matches. Use this with a real value from your IdP’s assertion trace to confirm the match mode before turning mapping on.

Worked examples

Active Directory via ADFS, groups as DNs

Assertion attribute memberOf carries CN=Change-Approvers,OU=Groups,DC=example,DC=com and CN=Domain Users,….

Create the role Change Approvers in Settings › RBAC and add Change-Approvers to its SSO group.
On the SAML2 page set Role attribute to memberOf, Match mode to Group DN, and turn on Auto-approve.
Test CN=Change-Approvers,OU=Groups,DC=example,DC=com: reduced to Change-Approvers, grants Change Approvers via SSO group. Domain Users matches nothing and is ignored.

Entra ID or Okta, group names with a prefix

Attribute groups carries rconfig-admin, rconfig-Read-Only, finance.

Set Role attribute to groups, Match mode to Regular expression, Pattern to ^rconfig-(.+)$.
rconfig-admin reduces to admin, which slugifies to the built-in admin role’s ident. rconfig-Read-Only reduces to Read-Only and matches the preset Read-Only role by ident. finance does not match the pattern and is ignored.

Entra ID sending group object IDs

Attribute http://schemas.microsoft.com/ws/2008/06/identity/claims/groups carries GUIDs.

Add the GUID to the SSO group of the role it should grant.
Set Match mode to Exact value.

Avoiding lockout

Role mapping refuses any SAML user, including administrators, whose groups match no active role.

Keep a local-password admin account and confirm you can log in with it before enabling role mapping. Local and LDAP logins are not affected by SAML role mapping.
Map an admin group first: either add your IdP admin group to the admin role’s SSO group, or have the IdP send a value that reduces to admin.
Use Test a value with real assertion values before saving.
If you are locked out, log in with the local account and clear the Role attribute on the SAML2 page to return to manual role assignment.

Logging

All of the following are written to the Application Log with event type auth (login events) or authentication (settings changes):

Every mapped login records the attribute name, the resolved role idents, the match mode, and a trace of each raw value, its reduced form and the role it matched (or none). Search the Application Log for resolved to [ when a user reports missing access.
Refused logins record no rConfig role assigned by the identity provider, or is missing from the assertion when the attribute was absent.
Enabling or disabling auto-approve and role mapping, and the attribute and match mode in use, are recorded when the settings are saved.

Troubleshooting

User is refused with “no rConfig role assigned”

Open the Application Log and find the resolved to [...] trace for that login. It shows each raw value and what it reduced to.
If values reduce to nothing, the match mode or pattern does not fit what the IdP sends. Test a raw value from the trace on the settings page.
If values reduce correctly but grant no role, check the role is active and that its SSO group (or ident) equals the reduced value.

User is refused with “attribute is missing from the assertion”

The IdP is not releasing the attribute, or under a different name. Enable SAML2_DEBUG=true and compare the attribute names in the assertion with the Role attribute setting. Both the attribute name and its friendly name are accepted.

Roles assigned in Users keep disappearing

Expected with role mapping on. Give the user the group at the IdP, or add the value the IdP already sends to the role’s SSO group.

Saving a role fails with “SSO group already maps to the role …”

Each SSO group value can grant only one active role. Remove it from the other role, or deactivate that role.

Pattern is rejected

The pattern must compile and contain exactly one capture group. Use (?:…) for grouping you do not want captured. Delimiters (/…/) are added for you; do not type them.

SSO with SAML - Connecting a generic SAML 2.0 identity provider
SSO with Shibboleth - Shibboleth-specific configuration
Roles and Permissions - Creating roles and setting their SSO group
Users - Manual approval and role assignment
Application Log - Where mapping traces and refusals are recorded

SAML Auto-Approval and Role Mapping