Configuring Microsoft Entra ID (OIDC with PKCE) SSO for Vantage

Environments: Production, and optionally Staging/UAT Purpose: Register Vantage in Microsoft Entra ID (formerly Azure Active Directory) so your users can sign in through NPI's Auth0 tenant using OpenID Connect (OIDC) with Proof Key for Code Exchange (PKCE).

This guide is for organizations whose security policy requires PKCE. If PKCE is not required, use Configuring Microsoft Entra ID SSO for Vantage.

Overview

Auth0's dedicated Microsoft Entra ID connection does not support PKCE. For PKCE, NPI connects to your tenant through Auth0's OpenID Connect enterprise connection instead, using the Authorization Code flow with PKCE pinned to S256.

For each sign-in, Auth0 creates a one-time secret (the code verifier) and sends only its SHA-256 hash (the code challenge) to Entra ID. When Auth0 redeems the authorization code, it must present the original verifier, so an intercepted code is useless to anyone else. PKCE works alongside the client secret, not instead of it.

Where PKCE is enforced. Entra ID validates PKCE on every request that includes a code challenge, but app registrations of the Web platform type have no setting to require it. Enforcement happens on NPI's side: the Auth0 connection is set to always send S256. You can confirm this yourself in Section 5.

Environment Values

Use the Staging/UAT values only if you want to test before going to production. Create a separate app registration for each environment.

1. Prerequisites

Before starting, verify:

• You can sign in to the Microsoft Entra admin center (https://entra.microsoft.com) with at least the Application Developer role, which is enough to register the app.
• Someone in your organization can grant tenant-wide admin consent, typically a Cloud Application Administrator, Application Administrator, or higher.
• If you have access to more than one tenant, you know which one holds your Vantage users.

2. Register the Application

The steps show Production values; for UAT, use the UAT column of the Environment Values table.

1. Sign in to the Microsoft Entra admin center. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the correct one.
2. Browse to Entra ID → App registrations and select New registration.
3. Complete the form:

4. Select Register.
5. On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID.

⚠️ Choose Web, not Single-page application (SPA). Auth0 redeems the authorization code from its servers with a client secret, which only the Web platform supports.

2.1 Add the backup Redirect URI

1. In your app registration, go to Manage → Authentication.
2. Under the Web platform, select Add URI and enter https://npi-prod.us.auth0.com/login/callback (UAT: https://npi-uat-2026-05-22.us.auth0.com/login/callback).
3. Leave Access tokens and ID tokens under Implicit grant and hybrid flows unchecked. Those flows bypass PKCE.
4. Select Save.

2.2 Create a Client Secret

1. Go to Manage → Certificates & secrets → Client secrets and select New client secret.
2. Enter a description, for example Auth0 OIDC - Vantage Prod, and choose an expiration.
3. Select Add, then copy the secret's Value immediately. Entra shows it only once.

✅ Copy the Value, not the Secret ID. ✅ Record the expiration date. Sign-in stops working when the secret expires, so create a replacement and send it to NPI before that date.

3. Configure Permissions and Token Claims

NPI's Auth0 connection requests the scopes openid, profile, and email, and Vantage needs the user's email to match their account.

3.1 API Permissions

1. In your app registration, go to Manage → API permissions.
2. Select Add a permission → Microsoft Graph → Delegated permissions, and add openid, profile, and email (under OpenId permissions). Keep the default User.Read.
3. Select Grant admin consent for <your tenant name>, then select Yes.

3.2 Optional Claims

For users who belong to your tenant, Entra ID adds email, given_name, and family_name to the ID token only when you request them. Add them explicitly:

1. Go to Manage → Token configuration and select Add optional claim.
2. Choose token type ID.
3. Check email, given_name, and family_name, then select Add.
4. If prompted to turn on the Microsoft Graph email permission, check the box and select Add.

The email claim comes from the user's Email (mail) attribute. Confirm your Vantage users have it set, and that it matches the email they were invited to Vantage with. If your users sign in with a UPN that differs from their email, tell NPI.

4. Share Details with the Vantage Team

4.1 Discovery URL

Auth0 reads your tenant's OpenID configuration from the v2.0 discovery endpoint, built from your Directory (tenant) ID:

https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration

Open it in a browser to confirm it loads. Entra's discovery document does not list supported PKCE methods, which is why NPI pins the connection to S256 rather than letting Auth0 detect it.

4.2 Final Deliverables

If you set up UAT too, send one set for each environment and label it.

? Share the client secret through a password manager share or another encrypted channel agreed with your implementation engineer. Do not send it over email.

5. Test the Connection

Once NPI confirms the connection is live, test with the user you named in Section 4.2. If you set up UAT, test there first, then repeat in Production.

5.1 Sign-in test

1. Open a private or incognito browser window.
2. Go to the Vantage login URL for the environment (Production: https://www.npi-digital.com; UAT: https://uat.npi-digital.com) and enter the test user's work email.
3. Confirm you are redirected to the Microsoft sign-in page, not the Vantage password prompt.
4. Sign in. You should land in Vantage, signed in as the test user, with no consent prompt.

5.2 Confirm PKCE is in use

1. Before step 2 above, open your browser's developer tools and select the Network tab.
2. After you are sent to Microsoft, find the request to login.microsoftonline.com/<tenant ID>/oauth2/v2.0/authorize.
3. Confirm its query string includes code_challenge= and code_challenge_method=S256.

If code_challenge is missing, send NPI a screenshot of the request; the connection is not enforcing PKCE.

5.3 Review the sign-in log (optional)

In Entra ID → Monitoring & health → Sign-in logs, filter by the app name and confirm the test sign-in shows Success. For a failure, the log entry's Failure reason and AADSTS code are the most useful things to send NPI.

6. Common Errors to Avoid

7. Frequently Asked Questions

Why not use the standard Microsoft Entra ID connection? Auth0's dedicated Microsoft Entra ID connection does not support PKCE. The OpenID Connect connection does, so it is the only Auth0 option when PKCE is required.

Do we still need a client secret if PKCE is on? Yes. Auth0 redeems the authorization code from its servers as a confidential client, so it authenticates with the client secret and proves PKCE. The secret proves the caller is Auth0; PKCE proves the caller is the one that started this sign-in.

Can Entra ID reject sign-ins that do not use PKCE? Not for Web platform app registrations: Entra ID validates PKCE whenever a code challenge is sent but has no setting to require one. NPI's connection is configured to always send S256, and Section 5.2 shows how to verify it.

Will group memberships or other custom claims reach Vantage? Unlike the dedicated Entra ID connection, the OpenID Connect connection can map additional ID token claims. If you need groups or other claims in Vantage, tell your implementation engineer before adding them in Token configuration.

Do we need to do anything when Microsoft rotates its signing keys? No. Auth0 reads Entra ID's current signing keys from the discovery document automatically.

8. Quick Checklist

• (Optional) UAT app registration created and tested before Production
• App registered as Single tenant on the Web platform
• Both redirect URIs added; implicit and hybrid flows left unchecked
• Client secret Value copied and expiration date recorded
• openid, profile, email delegated permissions added and admin consent granted
• email, given_name, family_name optional claims added to the ID token
• Tenant ID, client ID, secret, expiry, domains, and test user sent to NPI
• Test sign-in completed and code_challenge_method=S256 confirmed in the browser

Need Help?

If you encounter issues or need assistance, contact your Vantage implementation engineer or reach us at support@npi-digital.com.

Sources

• Auth0: Configure PKCE and Claim Mapping for OIDC Connections
• Auth0: Connect to OpenID Connect Identity Provider
• Microsoft: Microsoft identity platform and OAuth 2.0 authorization code flow
• Microsoft: Optional claims reference
• Microsoft: Register an application in Microsoft Entra ID