OIDC SSO with Entra ID - Integration Guide Field Details Document Type How-To Guide - SSO Integration Applies To Microsoft Entra ID, Any OIDC-compatible SaaS or Third-Party Application Audience 2nd Line / Systems Administrator / IT Engineer Author AK. Udofeh Last Updated March 2026 Overview This article covers how to configure Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol between Microsoft Entra ID and any third-party or SaaS application that supports OIDC for authentication. It is intended for systems administrators who need to integrate enterprise applications with Entra ID to centralise identity management, enforce MFA, and control user access. The guide covers App Registration in Entra ID, redirect URI configuration, required API permissions, and the standard OIDC configuration values expected by most OIDC-compliant applications.   Root Cause OIDC SSO works by delegating authentication to Entra ID as the Identity Provider (IdP). The application (Service Provider) redirects the user to Microsoft's authorisation endpoint, which authenticates the user and returns an ID token containing identity claims. The application then validates the token using signing keys retrieved from Microsoft's OIDC discovery document. Common Failure Points Redirect URI mismatch between the application config and Entra App Registration OIDC Issuer URL malformed (e.g. missing  /v2.0 , or a full URL stored where only a GUID is expected) Application server cannot reach Microsoft's discovery endpoint outbound API permissions not granted admin consent in Entra Client secret expired or incorrect Auto-discovery disabled, causing the application to expect manually specified signing keys   Before You Start Check Where You have Global Administrator or Application Administrator rights in Entra ID Entra ID → Roles and Administrators The target application supports OIDC (not only SAML) Application vendor documentation You know the exact Redirect URI format expected by the application Application vendor documentation Outbound HTTPS (port 443) from the application server to  login.microsoftonline.com  is permitted Firewall / network policy You have admin access to the application's configuration settings Application admin console or hosting environment A client secret can be created and stored securely Azure Key Vault or organisation secrets manager Step 1: Create an App Registration in Entra ID Navigate to  portal.azure.com > Entra ID > App Registrations > New Registration. Enter a meaningful display name (e.g.  AppName SSO ). Under Supported account types, select Accounts in this organisational directory only (Single tenant) unless multi-tenant access is required. Leave the Redirect URI blank for now -  you will add it in Step 3. Click Register. Note the following values from the   Overview   page - you will need these later: •    Application (client) ID - this is your OIDC Client ID •    Directory (tenant) ID - this is used to construct your OIDC Issuer URL Step 2: Create a Client Secret Inside the App Registration, go to Certificates & Secrets > Client Secrets > New client secret. Enter a description (e.g.  AppName OIDC Secret ) and set an appropriate expiry period. Click Add. Copy the secret   Value   immediately - it will not be displayed again after you navigate away. Store it securely in a secrets manager or vault. Step 3: Configure the Redirect URI Inside the App Registration, go to Authentication > Add a platform > Web. Enter the Redirect URI in the format specified by your application's documentation. A common pattern is: https:///oidc/callback     This value must exactly match what the application expects. Refer to the application's OIDC integration documentation for the precise path. Common variants include /auth/callback, /sso/callback, and /oauth/callback. Ensure "Access tokens" and "ID tokens" under Implicit grant and hybrid flows are NOT ticked unless the application vendor explicitly requires them. Click Save. Confirm the Redirect URI appears under Redirect URI configuration with Platform Type: Web. Step 4: Grant API Permissions Go to API Permissions > Add a permission > Microsoft Graph > Delegated permissions. Add the following permissions: Permission Purpose openid Required - enables OIDC sign-in profile Provides basic profile claims (name, etc.) email Provides the user's email address claim Click Grant admin consent for  and confirm. All three permissions should show a green tick with   "Granted for "   status.   Step 5:  Configure the Application Add the following configuration values to your application. The exact setting names vary per application — refer to your application's OIDC documentation. The values below represent the standard OIDC parameters used across most platforms: Configuration Key Value Auth Method / SSO Protocol oidc Client ID Application (client) ID from Entra App Registration Client Secret Secret value created in Step 2 Issuer URL https://login.microsoftonline.com//v2.0 Auto-Discovery true  (recommended — eliminates need to manually specify endpoints) Redirect / Callback URI Must match exactly what was registered in Step 3 Scopes openid profile email Critical: Issuer URL format:   The Issuer URL must contain only the tenant GUID in the path and must end with  /v2.0 . A common misconfiguration is storing a full URL in a variable and substituting it into the Issuer field, producing a doubled path such as  https://login.microsoftonline.com/https://login.../v2.0/v2.0 . This will cause discovery to fail. Correct format: https://login.microsoftonline.com/e21b46c3-367f-4ced-b138-2c57e76746f6/v2.0 Step 6:  Restrict Access via Enterprise Application (Recommended) By default, any user in your Entra tenant can attempt SSO into the application. To restrict access to specific users or groups: In Entra ID, go to Enterprise Applications > find your application by display name. Go to Properties > set "Assignment required?" to Yes > Save. Go to Users and groups > Add user/group > assign the relevant users or Entra security groups. Only assigned users will be permitted to authenticate. All others will receive an Entra-side access denied message before reaching the application.   Step 7: Optional: Group-to-Role Synchronisation If the application supports mapping identity provider groups to application roles, you can automate role assignment via Entra group membership: In the App Registration > Token configuration > Add groups claim > select Security groups > Save. In the application's OIDC settings, enable group synchronisation and set the groups claim name to  groups . In the application's role configuration, map each role to the corresponding Entra group Object ID (GUID). Entra sends group   Object IDs, not display names, in the token. Always use the group's Object ID when mapping groups to application roles -  not the group's display name. Troubleshooting OIDC Discovery Error  / Discovery endpoint unreachable Cause:  The application cannot fetch the OIDC discovery document from Microsoft, or the Issuer URL is malformed. Resolution: Verify the Issuer URL is not doubled > check error messages for patterns like https://login.microsoftonline.com/https:// ... Confirm the Issuer URL ends with  /v2.0  and contains only the tenant GUID (not a full URL). Test outbound connectivity from the application server to Microsoft:   bash curl -s " https://login.microsoftonline.com//v2.0/.well-known/openid-configuration " | head -c 200 If the  curl  fails, verify firewall rules permit outbound HTTPS (port 443) to  login.microsoftonline.com . Missing required configuration "keys" value  or similar Cause:  Auto-discovery is disabled or not correctly configured. The application is expecting manually specified JWKS signing keys. Resolution: Ensure auto-discovery is enabled in the application's OIDC settings. Confirm the Issuer URL is correct - a malformed URL will cause discovery to silently fail. Clear the application's configuration cache and restart the service. redirect_uri_mismatch Cause:  The Redirect URI registered in Entra does not exactly match the callback URL the application is generating or sending. Resolution: Confirm the application's configured domain uses  https://  and matches exactly. Update the Redirect URI in Entra: App Registration > Authentication > Web > Edit. Ensure no trailing slashes, port numbers, or scheme mismatches exist between the two values.   invalid_client Cause:  The Client ID or Client Secret is incorrect, or the client secret has expired. Resolution: Verify the Client ID matches the Application (client) ID in the App Registration overview  not the Object ID or any other GUID. Check the secret expiry date in Certificates & Secrets - create a new secret if expired. Confirm the secret Value is used (not the Secret ID, which is a different field). User authenticates successfully in Entra but receives an error or no access in the application Cause:  The user account was provisioned in the application with no role or permissions assigned. Resolution: Log in to the application as an administrator. Assign an appropriate role to the SSO-provisioned user account. To automate this for future users, configure a default role for SSO-registered accounts in the application's settings, or implement group-to-role synchronisation (Step 7). invalid_grant  or token validation failure Cause:  Clock skew between the application server and Microsoft's servers, or the authorisation code was already consumed. Resolution: Ensure the application server's system clock is synchronised via NTP. A skew of more than 5 minutes will cause token validation to fail. Confirm the application is not attempting to reuse an authorisation code - these are single-use and expire within seconds. Expected Outcome Factor Detail Resolution Time 30–60 minutes for initial configuration; 15 minutes for troubleshooting known issues User Impact Zero - SSO login is additive; existing local accounts remain functional during migration Recurrence Risk Low - primary recurring issue is client secret expiry; set a calendar reminder before the secret's expiry date Ongoing Maintenance Rotate client secrets before expiry; manage user access via Enterprise Application user/group assignments User Mapping & Role Assignment (Entra ID OIDC) This section explains how to configure user authorization and role mapping in Microsoft Entra ID for third-party applications using OIDC SSO. While authentication allows users to sign in, role mapping determines what permissions users receive inside the application after login. Overview Microsoft Entra ID supports two common authorization approaches for OIDC applications: Method Description Recommended Group Claims Maps Entra groups to application roles Legacy / Limited App Roles Assigns application-specific roles directly from Entra ID ✅ Recommended For modern OIDC integrations, App Roles are the preferred enterprise-grade approach because they are: More reliable Easier to manage Included consistently in OIDC tokens Better suited for role-based access control (RBAC) Recommended Approach - App Roles Step 1: Create App Roles Navigate to: Microsoft Entra ID > App registrations > > App roles Create roles required by the application. Example: Administrator Role Field Value Display name Application Admin Allowed member types Users/Groups Value AppAdmin Description Full administrative access Viewer Role Field Value Display name Application Viewer Allowed member types Users/Groups Value Viewer Description Read-only access Step 2: Assign Users or Groups Navigate to: Enterprise Applications → → Users and groups Assign: Users OR Security groups to the appropriate application role. Example: Group Assigned Role IT Administrators AppAdmin Monitoring Users Viewer Step 3: Configure Token Claims Once App Roles are assigned, Entra ID automatically includes the role assignment inside the OIDC token. Example token payload: "roles": [ "AppAdmin" ] This role claim can then be consumed by the third-party application for authorization and RBAC mapping. Group Claims (Alternative Method) Some applications use Entra security groups instead of App Roles. To enable group claims: App registrations → → Token configuration → Add groups claim However, this method has limitations: Tokens may omit groups if the user belongs to many groups Tokens may return "hasgroups": "true" instead of actual group IDs Additional Microsoft Graph permissions may be required Because of these limitations, App Roles are generally preferred. Common Permissions Required Depending on the application, the following delegated Microsoft Graph permissions may be required: Permission Purpose openid OIDC authentication profile Basic user profile email User email address GroupMember.Read.All Read user group memberships After adding permissions: API permissions → Grant admin consent Redirect URI Configuration The OIDC redirect URI configured in the third-party application must exactly match the Redirect URI configured in Entra ID. Navigate to: App registrations → → Authentication Example: https://app.example.com/login/oauth Common errors: Redirect URI mismatch Missing reply address HTTP vs HTTPS mismatch Incorrect callback endpoint Token Validation & Troubleshooting Microsoft provides a JWT inspection utility for validating OIDC tokens: jwt.ms This tool can be used to verify: roles claims group claims audience issuer scopes token structure Best Practices Prefer App Roles over Group Claims Use security groups for scalable role assignments Keep Redirect URIs HTTPS-only Use least-privilege Graph permissions Grant admin consent after permission changes Validate tokens using jwt.ms during troubleshooting Avoid hardcoding role logic where possible