Skip to main content

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

No comments to display

Back to top