dotauth

User Provisioning & Role Mapping

These settings decide whether dotCMS creates users at sign-in, how it matches returning users, and which roles they get. They apply to OIDC sign-in, SAML sign-in (with the differences noted in SAML provisioning), and each trusted IdP in headless authentication.

"Apply the same JIT provisioning strategy to interactive SSO and headless exchange."

Auto-Provisioning#

Setting	Default	Description
Auto-provision new users	On	Creates a dotCMS user on first successful sign-in. When off, only users who already exist in dotCMS can sign in.
Default roles	—	A comma-separated list of dotCMS role keys given to every provisioned user, for example `exampleRole1, exampleRole2`. Group mappings add roles on top of these. Include only access that every user in this scope should have, and leave it empty if there's no such role.

How Users Are Matched#

At each sign-in, dotCMS looks for an existing user in this order:

By email, but only when the IdP marks the email as verified (email_verified: true).
By IdP identity: a user ID derived from the provider type, issuer, and subject (sub). It is hashed when Hash user ID is on.

If neither matches and auto-provisioning is on, dotCMS creates a new user. That user gets a random password and cannot use native login unless an administrator resets it. On later sign-ins, dotCMS refreshes the user's first and last name from the IdP.

Migrating existing users. If your IdP doesn't send email_verified (Microsoft Entra ID doesn't by default), dotCMS can't match existing dotCMS accounts by email. It then tries to create a new user with the same email, and sign-in fails. Test with an existing account before switching production sign-in to SSO.

Role Behavior#

"How dotCMS reconciles a user's roles with the IdP-mapped roles." This setting runs at every sign-in.

Provisioning settings showing the Role behavior options and a Group → role mapping row

Option	What happens at each sign-in
Sync all (default)	Removes all existing roles, then adds the system access roles, default roles, and IdP group mappings. Keeps roles in sync with the IdP.
IdP groups only	Removes all existing roles, then adds only IdP group mappings. No system access roles or default roles are added.
Static only	Removes all existing roles, then adds only the system access roles and default roles. IdP groups are ignored.
Additive	Keeps all existing roles and adds the system access roles and default roles. IdP groups are ignored, and roles are never removed.
None	Does not change roles. Manage roles manually in dotCMS.

System access roles are DOTCMS_BACK_END_USER (when Redirect admin panel is on) and/or DOTCMS_FRONT_END_USER (when Redirect site login is on). A user needs the back-end role to use the admin panel.

Plan your role strategy carefully.

Sync all, IdP groups only, and Static only remove every role at each sign-in, including roles an administrator assigned by hand in dotCMS (such as CMS Administrator). Grant important roles through IdP group mappings or default roles.
With IdP groups only, users get no back-end access unless a group mapping grants DOTCMS_BACK_END_USER. Without it, they see "Your account does not have access to dotCMS."
If dotCMS can't fetch groups (for example, the Groups URL is unreachable), the sign-in is cancelled and the user's existing roles are left unchanged.

For a first rollout, start with Additive. It keeps the roles administrators have already assigned in dotCMS, so a mistake in group delivery or mapping can't remove anyone's access. Switch to Sync all only after you've confirmed that the IdP delivers the groups you expect and that each mapping grants the right role. See Rolling out SSO safely.

Group Security (OIDC Only)#

"Controls which IdP groups may resolve to dotCMS roles. Only mapped groups are honored by default."

Setting	Default	Description
Allow unmapped groups	Off	When off (recommended), only IdP groups with an explicit mapping grant roles. When on, dotCMS tries any unmapped group name as a dotCMS role key. For example, an IdP group named `CMS Administrator` would grant the administrator role. Turn this on only for IdP directories you fully control.
Role key filter (regex)	—	An optional regular expression that each final dotCMS role key must match (substring match), for example `^(dotcms\|CMS)` . Role keys that don't match are skipped. An invalid pattern blocks all group-derived roles until you fix it.

Group → Role Mappings#

"Apply roles based on IdP group membership." Click Add mapping to add a row:

Column	Example	Notes
IdP group	`dotcms-admins`	The group value exactly as the IdP sends it. Some IdPs send an ID rather than a display name; Microsoft Entra ID, for example, sends group object IDs.
dotCMS role	`CMS Administrator`	The dotCMS role key. Case-sensitive.

Without mappings, new users get only the default roles.