Microsoft Entra ID setup¶

A step-by-step walkthrough for connecting CertIntel to Microsoft Entra ID 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.

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.

Discovery URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

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. Record the expiry date yourself; CertIntel does not track client-secret expiry.

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 discovery URL / client ID / client secret from steps 2-3. The provider is created enabled; if you want it hidden until Entra is finished, open Edit configuration & role mappings, untick Enabled and save.
2. The page then shows the exact Redirect URI, Front-channel logout and Back-channel logout values for this provider.
3. Back in Entra: Authentication → Add a platform → Web, and paste the Redirect URI 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. Entra's v2.0 endpoints send the sid and iss values CertIntel requires; iss must equal the Issuer you entered in step 2, which is one more reason to use the v2.0 URLs.
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.

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
   • the same two prefixes also accept Auditor, AlertManager, CertificateIssuer and DNSDelegationManager; a custom role needs an explicit mapping row

   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. 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 unless the provider has a Fallback role. For a true "anyone in the tenant gets read-only", either set the provider's Fallback role to Viewer under Edit configuration & role mappings, or assign an app role to all users and map its value to Viewer.

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 Refresh discovery to confirm the document is reachable and advertises end_session_endpoint. The check also fails if the discovery host is not a public address or the document is oversized, compressed or not JSON.
5. Make sure Enabled is ticked and save.

Distribute the provider's Login link (/login?sso=<slug>, 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).
• 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.
• Signing out of Entra shows "You have been signed out" but the CertIntel session is still alive - the front-channel request did not carry sid and iss, or iss did not match the configured Issuer (typically a v1.0 vs v2.0 mismatch). Fix the Issuer; the session still ends on CertIntel's own sign-out.
• "Too many OIDC sign-in starts. Try again later." - the per-address or per-provider sign-in budget was exceeded, for example by a misconfigured redirect loop. Wait for the Retry-After interval.