dotCMS logodotCMS logo
dotCMS Github RepodotCMS Github RepodotCMS Discourse CommunityChat With Us
Access and Security

dotauth

Configuring Single Sign-On (SSO)

Single sign-on (SSO) sends dotCMS users to your identity provider to sign in. Each scope (System or a site) uses one protocol. This page covers the settings shared by both protocols; the protocol pages cover the rest:

Provisioning and role settings are on the same screen for both protocols; see User provisioning and role mapping. Before turning SSO on in production, read Rolling out SSO safely.

Choosing a Protocol#

Single sign-on page with OAuth 2.0 / OIDC selected, SSO enabled turned off, and the SSO is currently inactive banner

The Single sign-on page ("Configure browser-based administrator sign-in for this scope") starts with the Protocol section:

  • OAuth 2.0 / OIDC (Recommended): "Use Auth0, Okta, Azure AD, Keycloak, Google Workspace, or any OIDC-compliant IdP."
  • SAML 2.0: "Federated SSO via SAML 2.0 — common for enterprise IdPs like ADFS, Ping, or Shibboleth."

Selecting a protocol turns the SSO enabled switch on automatically. To prepare a configuration without affecting anyone, turn the switch off before saving. The page then shows a banner that reads, "SSO is currently inactive. You can configure and save settings without affecting users — turn on the SSO enabled switch above when you're ready."

With the switch on, the banner changes to "SSO is live." Edits take effect as soon as you save.

If you switch protocols while you have unsaved edits, dotCMS asks you to confirm. Existing sessions stay valid until they expire. The previous protocol's settings stay in the form until you save, so you can switch back. Saving a protocol deletes the other protocol's stored configuration for that scope.

Saving, Cancelling, and Clearing#

A footer at the bottom of the page shows Unsaved changes or No pending changes, and a count of validation issues if there are any. It has three buttons:

  • Save changes is enabled only when something has changed. When SSO is enabled, these fields are required:
    • OIDC: Issuer URL (normally filled by discovery), Client ID, and Client Secret
    • SAML: Entity ID
  • Cancel returns to the overview. If you have unsaved changes, it asks you to confirm first.
  • Clear configuration permanently deletes the configuration for this scope. To confirm, type clear configuration. Clearing the System scope stops SSO immediately for every site that inherits it. Clearing a site's configuration makes the site inherit from System again.

If the server rejects a save, it shows the validation message explaining why.

Login Behavior#

"Control which login surfaces redirect to the identity provider and how dotCMS identifies returning users."

SettingDefaultDescription
Redirect admin panelOnSigned-out requests to the admin panel (/dotAdmin/, /c/, /html/portal/login) are redirected to the IdP instead of the native login form.
Redirect site loginOffSigned-out requests to site login pages (/login, /dotCMS/login, /application/login/login) are redirected to the IdP.
Hash user IDOnHashes the IdP subject into a fixed-length dotCMS user ID. Recommended, because it avoids problems with special characters in IdP subjects. Choose before rollout. Changing it later doesn't lock out existing users, because dotCMS tries both ID formats, but new users get IDs in the new format.

These switches also decide which system access role a user gets at sign-in. With Redirect admin panel on, users get DOTCMS_BACK_END_USER. With Redirect site login on, users get DOTCMS_FRONT_END_USER. See Role behavior.