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

Rolling Out SSO Safely

Turning on SSO changes how every user in a scope signs in, so prepare the configuration while it's inactive and test it from a separate browser before you rely on it.

Before you start:

  • Make sure at least one administrator has a known dotCMS password (see Native login fallback).
  • In production, change the native-login bypass value with SSO_BYPASS_TOKEN, so that ?native=true alone isn't enough to skip SSO.
  • Decide on Hash user ID now; it should stay the same once users start signing in.

Configure and activate:

  1. Configure the scope with SSO enabled turned off. For a first rollout, set Role behavior to Additive and leave Groups URL empty unless you've designed and tested a group lookup.
  2. Click Save changes and confirm the saved notification. Reopen the configuration and check that the values persisted.
  3. Confirm that your IdP team has registered the exact Redirect URI shown in dotAuth.
  4. Turn SSO enabled on and save.

Test from a separate browser session:

  1. Keep your current administrator session open. You'll need it if sign-in fails.
  2. Open a new private window and go to https://<your dotCMS host>/dotAdmin/. Use a fresh window: if a window has ever loaded ?native=true, it keeps bypassing SSO for the rest of that browser session.
  3. Confirm that dotCMS redirects you to the expected IdP, sign in as a test user, and confirm that the browser returns through /api/v1/oauth/callback to the admin panel.
  4. Check the user's profile (including the email address), roles, visible tools, and content access.
  5. Repeat with an account that should have no elevated access.
  6. Sign out and sign in again.
  7. If you map groups, remove a test user from a mapped group at the IdP, sign in again, and confirm the role is removed (this requires Sync all or IdP groups only).

What counts as a successful test: the user lands in the admin panel with the expected identity and only the intended permissions, and can repeat the sign-in. A successful Discover confirms only that dotCMS found the IdP's endpoints, and a saved configuration isn't a test either. Neither shows that users can sign in.

If sign-in fails: in the administrator session you kept open, turn SSO enabled off for the scope and save. Native login works again on that scope immediately. If a site has its own override, check that site separately. If you no longer have an open session, use the native login fallback.

Native Login Fallback#

Native username/password login stays available as an administrator fallback, for example if the IdP is down or misconfigured.

If you still have an administrator session open, the simplest recovery is to turn SSO enabled off for the affected scope and save. Native login is then restored for that scope. This is why we suggest you keep a session open while testing.

Otherwise, use the bypass parameter. Add ?native=true (or your configured bypass value) to any dotCMS URL:

https://cms.example.com/dotAdmin/?native=true

The bypass lasts for the rest of the browser session, and ?native=false clears it. This matters when testing: a window that has used the bypass won't redirect to the IdP, so test SSO in a fresh private window. The bypass works for both OIDC and SAML.

Change the bypass value in production. Set the SSO_BYPASS_TOKEN property (or the legacy SAML_BYPASS_VALUE) to a value of your own, so that ?native=true alone isn't enough. Share the value only with administrators.

Make sure at least one administrator has a known dotCMS password before turning on SSO. Users created through SSO have random passwords.

API Tokens for REST, dotCLI, and WebDAV#

Browser SSO signs users in to the admin panel and site pages only. It doesn't authenticate REST calls, dotCLI, or WebDAV. For those, create an API token for the user in dotCMS. The user account must exist first, so either create it by hand or have the user sign in once through SSO. The exception is headless front ends, which can use headless authentication instead of API tokens.