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

dotauth

Microsoft Entra ID Quickstart

This walkthrough configures browser sign-in to the dotCMS admin panel against Microsoft Entra ID (formerly Azure AD) using OIDC. It uses the System scope; for a single site, open the site and choose Override for this site first.

Before you start, get these from your Entra administrator:

  • The tenant ID
  • The app registration's Application (client) ID
  • A client secret's value. Entra shows both a secret ID and a secret value; dotCMS needs the value.

Have them register the dotCMS Redirect URI as a Web platform redirect URI on the app registration. You'll copy it from dotAuth in step 4.

Configuring dotCMS#

  1. Go to Settings → dotAuth, click Configure SSO, and select OAuth 2.0 / OIDC. Turn SSO enabled off.
  2. Under Login behavior, leave Redirect admin panel on, Redirect site login off, and Hash user ID on.
  3. Under Connection, set Discovery URL to the tenant-specific issuer and click Discover: 
    https://login.microsoftonline.com/<tenant-id>/v2.0
  4. Enter the Client ID and Client Secret, and copy the Redirect URI to your Entra administrator. If several sites inherit this configuration, set External dotCMS URL under Advanced configuration so there's only one redirect URI to register.
  5. Leave Scopes as openid email profile, and leave Groups URL and Groups Response Path empty.
  6. Under Claim mapping, keep the defaults: email, given_name, family_name.
  7. Under provisioning, set Role behavior to Additive, and put in Default roles only the roles every Entra user should get.
  8. Save, then follow Rolling out SSO safely to turn SSO on and test.

Entra ID Considerations#

Entra ID differs from other OIDC identity providers in a few ways that affect sign-in and roles:

  • Group mapping doesn't work for browser sign-in. dotCMS reads browser-flow groups from userinfo, and Entra's userinfo response never includes groups or app roles. Manage these users' roles in dotCMS for now.
  • Existing users aren't matched by email by default, because Entra doesn't send email_verified. See How users are matched, and test with an existing account before you switch production sign-in.
  • Email can be missing for users without a mail address in Entra. Check the profile of your test users (see the email note under Claim mapping).

Group and app-role mapping does work for headless exchange, which reads claims from the id_token. To map Entra groups and app roles there:

  • For groups, have your Entra administrator add a groups claim to the token. Set Groups / roles claim to groups, and map each group's object ID (a GUID), not its display name.
  • For app roles, set Groups / roles claim to roles and map the app-role value, for example CMS.Editor.
  • Entra leaves the groups claim out entirely when a user belongs to more groups than fit in the token (200 for JWTs). Those users get no group-derived roles. Assigning groups to the application, or using app roles, avoids this.
  • Keep Allow unmapped groups off, and add one explicit mapping per permitted value.

Microsoft references: OpenID Connect on the Microsoft identity platform, UserInfo endpoint, Configure group claims and app roles in tokens.