Skip to content

Microsoft Entra ID setup

A step-by-step walkthrough for connecting CertIntel to Microsoft Entra ID (formerly Azure AD) as an OIDC provider. Read the OIDC / SSO overview first - it covers provider types, default-deny role mapping, the CertIntel.* convention and single logout, which this page assumes.

Note

Entra's portal navigation changes over time. The concepts below (app registration, app roles, redirect URIs, front-channel logout) are stable; exact menu wording may differ from what you see.

1. Create the app registration

  1. Azure Portal → Microsoft Entra ID → App registrations → New registration.
  2. Name it, e.g. CertIntel.
  3. Supported account types: Accounts in this organizational directory only (Single tenant) unless you specifically need multi-tenant sign-in.
  4. Leave Redirect URI blank - you add it in step 4, once you know the provider slug.
  5. Register.

2. Note the IDs you'll need

On the registration's Overview page, copy:

  • Application (client) ID - this is the Client ID in CertIntel. Not the Object ID.
  • Directory (tenant) ID - used to build the issuer and discovery URL.
Issuer:        https://login.microsoftonline.com/<tenant-id>/v2.0
Discovery URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Warning

Use the v2.0 URLs, not v1.0. CertIntel checks the discovery document's issuer against what you configure exactly - a v1.0/v2.0 mismatch is the most common reason a new Entra provider fails validation.

3. Create a client secret

  1. Certificates & secrets → Client secrets → New client secret.
  2. Give it a description and an expiry (Entra caps this at 24 months).
  3. Copy the secret's Value immediately - not the Secret ID. It is shown once.
  4. Paste it into CertIntel's Client secret field and set Client secret expires to match, so CertIntel can warn you before SSO breaks.

4. Create the provider in CertIntel, then finish the URIs in Entra

The callback and logout URLs depend on the provider slug, so the order matters:

  1. On Identity Providers, create the provider now with the issuer / discovery URL / client ID / client secret from steps 2-3. Leave it disabled until Entra is done.
  2. The page then shows the exact Callback URL, Front-channel logout URL and Back-channel logout URL for this provider.
  3. Back in Entra: Authentication → Add a platform → Web, and paste the Callback URL into Redirect URIs.
  4. In the same Web platform config, set Front-channel logout URL to the value CertIntel shows. Entra documents a front-channel logout URL, not an OIDC back-channel one - leave CertIntel's back-channel URL unconfigured for Entra.
  5. Do not enable anything under Implicit grant and hybrid flows. CertIntel uses Authorization Code + PKCE and needs none of it.

5. Define app roles

CertIntel reads roles from a token claim. Entra app roles are the recommended source, not the groups claim.

Why app roles, not groups

Once a user is in more than ~200 groups, Entra replaces the groups claim with an unusable "overage" indicator. Since CertIntel treats "no recognised role claim" as a rejection (default-deny), that would lock affected users out unpredictably. App roles are scoped to this one application and have no such limit.

  1. On the app registration: App roles → Create app role.

  2. Create one role per level of access. For a tenant-wide provider, the recommended values (these match the CertIntel.* convention, so no explicit mapping row is even required):

    • CertIntel.TenantWide.Administrator - admin across all orgs + tenant administration
    • CertIntel.TenantWide.Operator / CertIntel.TenantWide.Observer / CertIntel.TenantWide.Viewer
    • CertIntel.AllOrgs.Administrator / .Operator / .Observer / .Viewer - same reach, without tenant administration

    For a single organization, use CertIntel.Org.<org-id-or-slug>.<Role>. For an organization-bound provider, plain values such as CertIntel.Administrator also work - add them as explicit mapping rows - because the connection already pins every user to its organization. For a platform-wide provider (platform admins only), use CertIntel.PlatformWide.Administrator / .Operator / .Observer. 3. Allowed member types: Users/Groups. 4. The Value is exactly the string that appears in the token's roles claim - that is what you type into CertIntel's mapping table, not the display name.

6. Assign users / groups to those roles

  1. Go to Enterprise applications, find this app.
  2. Users and groups → Add user/group; assign each person (or group) the app role matching the access they should get.
  3. Anyone not assigned an app role can still complete the sign-in handshake, but their token carries no recognised role claim - which CertIntel treats as a rejected login, not a Viewer fallback. For a true "anyone in the tenant gets read-only", configure a fallback role on the provider in CertIntel instead.

7. API permissions

CertIntel requests only openid, profile and email; it does not call Microsoft Graph. User.Read can be removed if the portal added it. No admin-consent grant is needed.

8. Map roles in CertIntel and finish

  1. Edit the provider you created in step 4.
  2. Role claim: leave as roles.
  3. For any app-role value that is not a CertIntel.* convention value, add a role mapping pointing at the matching CertIntel role. The value must match exactly; an authenticated user with no matching value is denied and not provisioned.
  4. Click Test to confirm discovery is reachable, the issuer matches, and single logout is supported.
  5. Check Enabled and save.

Distribute the direct link /auth/oidc/<slug>/start (shown on the Identity Providers page) to the first federated user; the shared login page's email discovery picks the provider up automatically once at least one of its users exists.

Troubleshooting

  • "Single Logout is required; discovery has no end_session_endpoint" - you used the v1.0 discovery URL. Use v2.0 (step 2).
  • "issuer does not match" - the Issuer field isn't byte-for-byte what Entra's discovery document reports. Re-copy it from step 2.
  • Sign-in succeeds but the user is immediately rejected - a role-mapping mismatch. The app-role value (not display name) must match a mapping or a CertIntel.* value exactly, and the user needs that app role actually assigned under Enterprise applications → Users and groups.
  • An IdP change hasn't taken effect - role assignment resyncs on the user's next sign-in, not continuously.