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

dotauth

Managing Configurations

The dotAuth screen lists the System configuration and every site. This page covers reading that screen, giving a site its own configuration, and moving configuration between environments.

The dotAuth Overview Screen#

Go to Settings → dotAuth.

dotAuth overview showing the System identity provider card and a site list with Overridden, Inherits, and Disabled sites

If no System configuration exists yet, the page shows No identity provider configured, with two buttons:

  • Configure SSO opens the System single sign-on settings.
  • Configure headless opens the headless authentication settings.

Once the System scope is configured, a System identity provider card replaces the empty state. It shows:

  • Whether the System scope is Configured or Not configured
  • The System protocol (OAuth 2.0 / OIDC, SAML 2.0, or None)
  • A Headless enabled tag when headless exchange is set up
  • A Download SP Metadata action when the System protocol is SAML

Site List#

Below the System card, a table lists every site on the instance:

ColumnValues
SiteSite name and identifier
SSO protocolOAuth 2.0 / OIDC, SAML 2.0, → Inherits (site uses the System configuration), or — (none)
SSOOverridden (site has its own configuration), Inherits (site uses System), or Disabled (nothing configured)
HeadlessInherits if System headless is configured, otherwise Disabled. Headless settings are System-wide only.

The SSO column shows where a site's configuration comes from. It does not show whether the SSO enabled switch is on. Open the site to check.

Use the search box to filter by site name, and the filter buttons to narrow the list:

  • All
  • Overrides: sites with their own configuration
  • SSO on: sites that are Overridden or Inherit SSO
  • Headless on: sites that inherit headless exchange
  • Disabled: sites with neither SSO nor headless

Click a row (or its › chevron) to open that site's SSO settings. SAML rows also have a Download SP Metadata icon.

The toolbar also has Import and Export. See Exporting and importing configuration.

Per-Site Configuration#

Each site can use its own IdP and protocol. For example, a partner portal can sign in through Okta while an employee intranet uses Entra ID, all on one dotCMS instance.

How a site's configuration is resolved:

  • A site without its own configuration inherits the System configuration.
  • A site with its own configuration (a site override) uses only that configuration. The System settings are not merged in.

To create a site override:

  1. On the dotAuth overview, click the site's row.

  2. The page shows: "This site is inheriting the System default. Saving will create a site-specific override." The form is read-only.

    A site inheriting the System configuration, with a read-only form, the inheriting banner, and the Override for this site button

  3. Click Override for this site. The form unlocks, pre-filled with the inherited values, and the banner changes to "You are overriding the System provider for this site."

  4. Make your changes and click Save changes.

To remove a site override, open the site and click Clear configuration. The site goes back to inheriting from System.

To turn SSO off for one site while System has it on, create a site override using the same protocol as the System configuration with SSO enabled off. An override that uses a different protocol doesn't stop the System protocol from applying (see Limitations).

SSO Is Per Site, Not Per Folder#

dotAuth applies SSO per site (host). You can't assign a different IdP to a folder or path within a site. If your sites are organized as folders under one host, sign users in with the site's IdP and restrict each folder with dotCMS permissions:

  1. Create a dotCMS role for each audience, and note its role key.
  2. Map the IdP group for that audience to the role in Group → role mappings.
  3. Grant the role permissions on the folder, and remove anonymous access to it.

Users are provisioned with the mapped roles at sign-in, and folder permissions decide what they can reach.

If you need a separate IdP for one audience, create a separate dotCMS site for it (for example, partners.example.com) and give that site its own override.

Gating Front-End Content#

To require sign-in for front-end content:

  1. Turn on Redirect site login.
  2. Remove CMS Anonymous read access from the pages, folders, or files you want to protect, and grant read access to the roles your users receive.

When a signed-out visitor requests protected content, dotCMS sends them to the site login, which redirects to the IdP. After sign-in, dotCMS returns them to the page they requested. The SAML front-end login example shows a worked permission setup; the same pattern applies to OIDC.

For headless front ends, use headless authentication instead.

Exporting and Importing Configuration#

Use export and import to move dotAuth configuration between environments, such as from staging to production, or to restore it after a data refresh. Both require an administrator.

Export (overview toolbar → Export):

  1. Enter an export password of 14–32 characters.
  2. Click Export. dotCMS downloads one encrypted file (dotauth-appSecrets.export). It contains the OAuth/OIDC, SAML, and headless configuration for the System scope and every site, including client secrets and private keys. Store it securely.

Import (overview toolbar → Import):

  1. Choose the .export file.
  2. Enter the password used when it was exported.
  3. Click Import. Imported configurations overwrite existing ones.

Notes:

  • The file may contain only dotAuth configurations, or the import is rejected.
  • Site configurations are matched by site identifier, so each site must exist in the target environment.
  • dotCMS saves configurations one at a time as it imports them. If an error occurs partway, the configurations before it have already been saved. Review the overview afterwards.