dotauth

OAuth 2.0 / OIDC Settings

These settings appear when you choose OAuth 2.0 / OIDC as the protocol. The Login behavior switches at the top of the form are shared with SAML.

Connection#

"Where dotCMS sends users to authenticate, and how it talks back to your IdP."

OIDC Connection section after discovery, showing the Configured by discovery panel, the Redirect URI with a copy button, and a stored client secret

Field	Description
Discovery URL	Your IdP's issuer or base URL, for example `https://idp.example.com/oauth2/default`, or the full `/.well-known/openid-configuration` URL. dotCMS adds the `.well-known` suffix only if it's missing. Click Discover to fetch the IdP's endpoints. On success, a read-only Configured by discovery panel lists the Issuer, Authorization, Token, JWKS, Userinfo, and Logout URLs.
Client ID	From your IdP's application registration (sometimes called Application ID).
Client Secret	Encrypted at rest. Once saved, it shows as Secret stored and cannot be read back. Click Replace to enter a new one. The secret stays on the dotCMS server, which sends it to the token endpoint using `client_secret_basic`; it never reaches the browser.
Redirect URI	Read-only, with a copy button. Register this exact value as an authorized redirect URI in your IdP. It has the form `https://<host>/api/v1/oauth/callback`, where `<host>` should be the public hostname people actually use to reach dotCMS.

Important: redirect URIs for System-level configurations. dotCMS builds the redirect URI from the host the user is signing in on. If you configure OIDC at the System level, each site that inherits it sends its own https://<site hostname>/api/v1/oauth/callback, and you must register every one of them at the IdP. To use a single redirect URI instead, set External dotCMS URL under Advanced configuration.

Advanced Configuration#

Expand Advanced configuration under the Connection section to see:

Field	Default	Description
External dotCMS URL (optional)	—	Overrides the public dotCMS URL used to build the redirect URI. For example, `https://cms.example.com` becomes `https://cms.example.com/api/v1/oauth/callback`. Use this behind proxies or to pin one redirect URI for a System-level configuration.
Issuer URL	Filled by discovery	Must match the `iss` claim in tokens. Shown here only until discovery succeeds; after that it appears in the discovery panel.
Scopes	`openid email profile`	Space-separated. `openid` is required.
Groups URL (optional)	—	An endpoint dotCMS calls with the user's access token, for IdPs that can't put groups in token claims (for example Google Workspace or GitHub). Supports `{email}` and `{sub}` placeholders, which dotCMS fills from the user's verified claims.
Groups Response Path (optional)	—	A dot-path that picks group names out of the Groups URL response, with `[]` marking the array. Examples: `memberships[].groupKey.id` (Google Cloud Identity), `groups[].email` (Google Directory), `[].slug` (GitHub). Leave empty if the endpoint returns a plain JSON array of strings or `{"groups": [...]}`.

The OIDC form has no fields for entering endpoints by hand. dotCMS gets the authorization, token, userinfo, JWKS, and logout endpoints from discovery, so your IdP must publish a standard /.well-known/openid-configuration document.

Claim Mapping#

"Map id_token / userinfo claims to dotCMS user fields."

Field	Default	Description
Email	`email`	The claim containing the user's email address. dotCMS uses it as the primary identifier.
Groups / roles claim	`groups`	The claim containing group or role memberships, used for group-to-role mapping. This is often a custom claim; check your IdP's documentation.
First name	`given_name`
Last name	`family_name`

Note: In the browser sign-in flow, dotCMS reads the email and groups from the IdP's userinfo response, not from the id_token. If your IdP puts groups only in tokens, browser sign-in doesn't see them unless you configure a Groups URL lookup. Headless exchange is different: it reads claims from the id_token.

Microsoft Entra ID: group and app-role mapping doesn't work for browser sign-in in current releases. Entra puts groups and app roles in its tokens, and its userinfo response can't be configured to include them. Setting Groups / roles claim alone therefore assigns no roles. Until this changes, manage Entra users' roles in dotCMS (for example with Additive and Default roles). Headless exchange isn't affected. See Quick start: Microsoft Entra ID.

Email isn't guaranteed. Configuring an email claim doesn't guarantee that the IdP returns an email for every user. If dotCMS gets no email, or the address fails dotCMS's email validation, it creates the user with a placeholder address, <userId>@fakedotcms.com, and can't match that user by email later. Addresses whose top-level domain is longer than four characters (for example user@corp.systems) currently fail this validation. Check the user's profile after your first test sign-in.

Provisioning and Role Mapping#

See User provisioning and role mapping.

Session Behavior#

Field	Description
Logout URL	Filled by discovery from the IdP's `end_session_endpoint`. When the IdP publishes one, signing out of dotCMS also ends the user's IdP session (OIDC RP-initiated logout). dotCMS also revokes the access token if the IdP has a revocation endpoint.

Google Workspace Groups#

Google doesn't put group memberships in its sign-in tokens, so dotCMS has to look them up after sign-in. When Discover returns Google's issuer (https://accounts.google.com), dotCMS offers to set this up.

The prompt is titled Google Workspace detected, and offers, "We can set up dotCMS to look up each user's groups from Google after they sign in, so group-to-role mappings work."

Choose Set up group lookup to fill in the following, then review the values under Advanced configuration and save. Only empty fields are filled.

Scopes               openid email profile https://www.googleapis.com/auth/cloud-identity.groups.readonly
Groups URL           https://cloudidentity.googleapis.com/v1/groups/-/memberships:searchDirectGroups?query=member_key_id=='{email}'
Groups Response Path memberships[].groupKey.id

Choose Not now to leave the form unchanged.

Google-side prerequisites. In your Google Cloud project:

Enable the Cloud Identity API.
Add the cloud-identity.groups.readonly scope to your OAuth consent screen.

If either is missing, sign-in fails. This is intentional: dotCMS never signs a user in with incomplete group information, because that could strip their roles. Group names returned by Google are group email addresses, so map those in Group → role mappings.

dotCMS follows Google's nextPageToken pagination, up to 20 pages by default (see OAUTH_GROUPS_MAX_PAGES).