dotauth

Troubleshooting and Limitations

Known limitations of dotAuth, and fixes for common problems.

Limitations and Considerations#

Removing a user at the IdP blocks future SSO sign-ins but doesn't end open dotCMS sessions. For immediate offboarding, also deactivate the user in dotCMS. Deactivation also invalidates their headless sessionRefs on the next request.
Headless sessionRefs last until they expire. Disabling a trusted IdP or turning off headless exchange doesn't end sessionRefs that were already issued. Use Revoke all sessionRefs to end them.
SessionRefs are stored in the dotCMS cache. In a clustered deployment, use a shared cache (such as Redis) or sticky sessions so a sessionRef is recognized on every node. Restarting the server ends all sessionRefs.
Native login stays available through ?native=true as an administrator fallback.
Migrating from the OAuth plugin means re-entering the configuration in dotAuth. The plugin can keep running until you switch. Existing users are matched by verified email, so test before switching (see How users are matched).
System-level OIDC requires every inheriting site's redirect URI to be registered at the IdP, unless you set External dotCMS URL.
Microsoft Entra ID group and app-role mapping isn't supported for browser sign-in. Browser sign-in reads groups from userinfo, which Entra doesn't populate with groups or app roles. Headless exchange reads the id_token and isn't affected. See Quick start: Microsoft Entra ID.
Email addresses with a top-level domain longer than four characters (such as .systems or .agency) fail dotCMS's email validation. Those users are created with a @fakedotcms.com placeholder address and can't be matched by email.
SAML role mapping uses IdP group names directly as dotCMS role keys. Group → role mappings entered in dotAuth for SAML don't currently take effect.
Mixing protocols across scopes. If the System scope uses SAML and a site override uses OIDC (or the other way round), the System protocol can still apply to that site. To control a site fully, override it with the same protocol as the System configuration.
Headless exchange is configured instance-wide, not per site.
One interactive SSO configuration per site. A site can't offer a choice of several IdPs at sign-in, and an IdP can't be assigned to a folder or path. See SSO is per site, not per folder.
No SCIM provisioning. Users are created at sign-in, not synced ahead of time.

Troubleshooting#

When you collect server logs for a support ticket, remove client secrets, tokens, and sessionRefs first.

Symptom	Likely cause	What to do
dotAuth doesn't appear under Settings	The instance is older than 26.08.24-01, or your role's menu layout doesn't include the dotAuth tool.	Check the dotCMS version, and add dotAuth to a menu layout you have (it's normally next to Apps). See Before you begin.
Discover fails	The URL is wrong, the IdP is unreachable from the dotCMS server, or the URL was rejected by the SSRF guard.	Check the URL (an issuer/base URL or the full `.well-known` URL both work). Check that the dotCMS server, not just your browser, can reach the IdP through any firewall or proxy.
SSO is enabled but users still see the native login form	The changes weren't saved, the switches are off, the site has its own override, the browser window has used the native-login bypass, or dotCMS couldn't load the IdP configuration (for example because a URL was rejected by the SSRF guard).	Confirm that the right protocol is selected, that SSO enabled and Redirect admin panel (or Redirect site login) are on, and that you saved. Check whether the site inherits this scope. Test in a fresh private window. Then re-run Discover and check the server log for OAuth validation warnings.
IdP shows a "redirect URI mismatch" error	The redirect URI isn't registered at the IdP.	Copy the Redirect URI shown in dotAuth and register it exactly. For System-level configurations, register each site's URI or set External dotCMS URL.
Redirected to `/?error=oauth+state+mismatch`	The sign-in started on a different host or the session expired.	Start sign-in again from the same host. Check proxy and cookie settings.
Redirected to `/?error=oauth+callback+failed`	Token exchange, token validation, user matching, or group lookup failed.	Check the client ID, the current client secret value, and the issuer, then the server log. Common causes are an expired or wrong secret, a missing `email_verified` claim for an existing user, or a Google Groups URL without the Cloud Identity API enabled.
"Your account does not have access to dotCMS"	The user signed in but has no back-end role.	Turn on Redirect admin panel, add the role to Default roles, or map an IdP group to `DOTCMS_BACK_END_USER`. Check Role behavior.
User signs in but has fewer tools or less content access than expected	Signing in through the IdP grants only the roles dotAuth assigns. The user's roles or the roles' permissions and menu layouts don't cover what they need.	Check the user is active, then check Default roles, Role behavior, and group mappings, and the permissions and layouts of the resulting roles.
New users have `@fakedotcms.com` email addresses	The IdP didn't return an email, or the address failed dotCMS's email validation (for example, a top-level domain longer than four characters).	Check Email under Claim mapping and what the IdP returns. See the email note under Claim mapping.
Microsoft Entra ID users get no roles from group mappings	Browser sign-in reads groups from userinfo, which Entra doesn't populate.	This is a current limitation. Manage these users' roles in dotCMS. See Quick start: Microsoft Entra ID.
Users lose roles assigned by hand in dotCMS	Sync all, IdP groups only, or Static only resets roles at each sign-in.	Grant those roles through mappings or default roles, or use Additive or None.
Group mappings have no effect (OIDC)	The groups claim name is wrong, groups aren't in the userinfo response, or the role key filter or a mapping's role key doesn't match.	Check Groups / roles claim, check that role keys match exactly (case-sensitive), and check the regex.
Headless exchange returns `401 id_token validation failed`	Audience mismatch, expired token, or wrong nonce.	Set Expected audience to your SPA's `aud` value, and send the same nonce used in the authorization request.
Headless exchange returns `403 Origin not allowed`	The browser origin isn't listed exactly.	Add the exact origin (scheme + host + port, no trailing slash).
SAML sign-in fails after saving	The SP keypair was regenerated.	Upload the new SP certificate or metadata to your IdP.
SAML sign-in fails after upgrading to 26.10.05-01 or later	The SAML configuration had validation type None, which is now treated as requiring a signed response and a signed assertion.	Turn on exactly the signatures your IdP sends under Signing & encryption, and save.
SAML users don't get the expected roles	IdP role names don't exactly match dotCMS role keys. dotCMS skips names with no matching role.	Rename the IdP groups, or use `role.key.substitution` / `remove.roles.prefix` under Additional properties.