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://<your-app-domain>/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 <your tenant> and confirm.

All three permissions should show a green tick with "Granted for <tenant>" 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/<Directory (tenant) ID>/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/<tenant-id>/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:

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
>  <Your Application>
>  App roles

Create roles required by the application.

Example:

Administrator Role

Viewer Role

---

Step 2: Assign Users or Groups

Navigate to:

Enterprise Applications
→ <Your Application>
→ Users and groups

Assign:

• Users
  OR
• Security groups

to the appropriate application role.

Example:

---

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
→ <Your Application>
→ 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:

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
→ <Your Application>
→ 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