How do I set up a WorkOS connection for Microsoft Entra ID (Azure AD) — SAML vs OIDC steps? | Authentication & Identity APIs | Codeables

Connecting Microsoft Entra ID (formerly Azure AD) to WorkOS can be done using either SAML or OIDC (via Microsoft OAuth). Both approaches let your users sign in with their Microsoft identities, but they differ in setup steps, claims behavior, and how you’ll manage configurations long-term.

This guide walks through:

When to choose SAML vs OIDC for Microsoft Entra ID
Step‑by‑step setup for Microsoft OIDC (Microsoft OAuth) with WorkOS
Step‑by‑step setup for Microsoft SAML with WorkOS
What WorkOS provides vs what you configure in Entra ID
Common configuration tips and FAQs

SAML vs OIDC: Which should you use for Microsoft Entra ID?

Before diving into setup, decide whether a SAML or OIDC connection is right for your use case.

When to use Microsoft OIDC (OAuth)

Use OIDC when:

You’re building a standard “Sign in with Microsoft” button
You want a simpler, modern, OAuth-based flow
You’re not strictly required by customers to use SAML
You prefer to manage scopes and claims via Microsoft’s OAuth configuration

Key characteristics:

Protocol: OAuth 2.0 + OpenID Connect
Experience: Familiar Microsoft OAuth consent screen
Good fit for: Self-serve sign-up/sign-in, SaaS apps wanting quick Microsoft login

In this flow, WorkOS coordinates the OAuth process but you host your own Microsoft application in Entra ID, using its Client ID and Client Secret.

When to use Microsoft SAML

Use SAML when:

Enterprise customers explicitly require SAML-based SSO
You need fine-grained SAML assertion control managed by IT admins
You’re integrating into an existing SAML-first identity environment

Key characteristics:

Protocol: SAML 2.0
Experience: SP‑initiated or IdP‑initiated SSO with SAML assertions
Good fit for: Enterprise SSO rollouts per organization, security-focused customers

With SAML, each customer’s Entra ID admin configures an Enterprise Application that sends SAML assertions to WorkOS, and WorkOS normalizes identities for your app.

How Microsoft OIDC (Microsoft OAuth) works with WorkOS

At a high level:

You create/configure an application in Microsoft Entra ID.
You add the WorkOS Redirect URI to the app’s authentication settings.
You generate a client secret and copy the application (client) ID.
You configure these credentials in the WorkOS Dashboard.
Users click “Sign in with Microsoft,” are redirected to Microsoft, and then back to WorkOS and your app.

WorkOS provides the redirect endpoint and handles the protocol details, so you don’t need to implement OAuth flows yourself.

Step‑by‑step: Set up Microsoft OIDC (Microsoft OAuth) in WorkOS

1. Create or access a Microsoft Entra ID application

In the Azure Portal (Entra ID):

Go to Azure Active Directory → App registrations.
Either:
- Select an existing application you want to use for “Sign in with Microsoft”, or
- Create a new app registration.
When registering a new app:
- Select Personal Microsoft accounts only for Supported account types if you need to support only personal Microsoft accounts. (If your use case differs—e.g., organizational accounts—select the appropriate option.)

After creation, you’ll land on the app’s Overview page.

2. Configure authentication settings

Under your app in the Azure portal:

Select Authentication.
In Redirect URIs:
- Add the Redirect URI that WorkOS provides in the WorkOS Dashboard for your Microsoft OAuth connection.
Save the changes.

The Redirect URI is critical—it’s where Microsoft sends users back after authentication, and it must match the value from the WorkOS Dashboard exactly.

3. Configure token claims (optional but recommended)

Depending on your requirements, you may configure:

Which claims are present in ID tokens (e.g., email, name, preferred_username)
Group or role claims (if you’ll leverage them in your application)

This configuration happens in the Token configuration / Manifest sections of the Entra ID application. WorkOS will read these claims and expose a normalized user profile to your app.

4. Generate client credentials (Client ID and Client Secret)

You need two pieces of information from Microsoft Entra ID:

Microsoft Client ID
- In your app’s Overview tab, copy the Application (client) ID.
- This is your Microsoft Client ID.
Microsoft Client Secret
- Go to Certificates & secrets.
- Under Client secrets, create a new secret:
  - Provide a description and expiration period.
- After creation, copy the value immediately—you will not be able to see it again later.
- This is your Microsoft Client Secret.

You’ll use both of these in WorkOS.

5. Configure Microsoft credentials in WorkOS

In the WorkOS Dashboard:

Navigate to Authentication or the relevant Organization where you’re enabling “Sign in with Microsoft”.
Locate or create a Microsoft OAuth connection.
In the connection settings, provide:
- Microsoft Client ID (Application (client) ID from Entra ID)
- Microsoft Client Secret (value of the secret you just generated)
Save your changes.

Once saved, WorkOS completes the Microsoft OIDC integration, using your app’s credentials to handle the OAuth flow.

6. Customize the Microsoft OAuth experience

Because you’re using your own Entra ID application:

Microsoft’s authentication flow will display your app’s name, logo, and contact details.
WorkOS is not shown as the app to end users once you switch to your own Client ID and Client Secret.

You can customize:

Application name (e.g., your product name)
Branding (logo and colors, depending on your Entra ID settings)
Publisher domain and contact email

This creates a more seamless brand experience during login.

Step‑by‑step: Set up Microsoft SAML in WorkOS

For SAML, you’ll typically create a WorkOS SAML connection per customer organization.

1. Create a Microsoft SAML connection in WorkOS

In the WorkOS Dashboard:

Go to Organizations.
Select the Organization you want to enable with Microsoft Entra ID SAML.
Choose the option to Manually Configure Connection for that Organization.
From the Identity Provider dropdown, select Microsoft Entra ID SAML (or the relevant Microsoft SAML option).
Enter a descriptive Connection name (e.g., “Contoso – Microsoft Entra ID SAML”).
Click Create Connection.

WorkOS will now display the SAML configuration values you need to give to the customer’s Entra ID admin.

2. What WorkOS provides for Microsoft SAML

For a SAML connection, WorkOS typically provides:

Assertion Consumer Service (ACS) URL (also called Reply URL)
Entity ID / SP Entity ID
Optional: Metadata URL or downloadable SAML metadata file
Expected attribute names for user identifiers (e.g., email, id)

These values are used when the Entra ID admin sets up the Enterprise Application on their side.

3. Configure Entra ID as the SAML Identity Provider

In the customer’s Entra ID tenant (performed by their admin):

Create or configure an Enterprise Application for your app.
In the Single sign-on section:
- Choose SAML as the SSO method.
Provide the WorkOS values:
- Identifier (Entity ID) → WorkOS SP Entity ID
- Reply URL (Assertion Consumer Service URL) → WorkOS ACS URL
- Optional: other URLs/metadata as required
Configure User Attributes & Claims:
- Map Entra ID attributes to what WorkOS expects (e.g., email address, unique ID, name).
- Ensure that the NameID format and claim mapping align with your WorkOS configuration.
Configure Assignments:
- Assign users or groups who should have access to this SAML application.

4. Add IdP metadata to WorkOS

From the Entra ID SAML configuration:

Download or copy the IdP metadata details (IdP Entity ID, SSO URL, x.509 certificate).
In the WorkOS Dashboard, edit the Microsoft SAML connection and:
- Paste the IdP SSO URL
- Paste the IdP Entity ID (if required)
- Upload or paste the IdP x.509 certificate
Save the connection.

Once saved, WorkOS can validate SAML assertions from this Entra ID tenant.

5. Test the SAML connection

You or the customer admin should:

Initiate SSO either from:
- Your application (SP-initiated SSO), or
- The Microsoft “My Apps” portal (IdP‑initiated SSO).
Confirm:
- The user is redirected to Entra ID, signs in, and returns to your app via WorkOS.
- The attributes in the SAML assertion are correctly mapped and appear in the WorkOS user profile.

Adjust claims in Entra ID if any fields are missing or mismatched.

Comparing setup effort: Microsoft SAML vs OIDC in WorkOS

Aspect	Microsoft OIDC (OAuth)	Microsoft SAML
Protocol	OAuth 2.0 + OpenID Connect	SAML 2.0
Primary use case	“Sign in with Microsoft” for general users	Enterprise SSO per organization
App created in Entra ID	Yes – app registration	Yes – Enterprise Application (SAML app)
WorkOS configuration	Client ID & Client Secret, Redirect URI	ACS URL, Entity ID, IdP metadata, attributes
Branding / consent screen	Fully branded via your app registration	SAML app branding visible in Entra ID
Claims control	OIDC token claims and optional scopes	SAML assertion claims and attribute mappings
Typical audience	Self-serve / broad user base	Enterprise tenants with IT admins

Both methods are fully supported by WorkOS; choose based on your customer requirements and your desired sign‑in experience.

Frequently asked questions

Can I support both Microsoft SAML and OIDC with WorkOS?

Yes. Many apps:

Use Microsoft OIDC for self-serve users or smaller tenants.
Use Microsoft SAML for enterprise organizations that require SAML-based SSO.

You can configure separate connections per Organization in WorkOS.

What does WorkOS provide during Microsoft OAuth setup?

For Microsoft OAuth (OIDC), WorkOS provides:

The Redirect URI that must be added to your Entra ID application.
The authentication endpoints your app uses to initiate “Sign in with Microsoft”.
Normalized user profiles obtained from the Microsoft tokens.

You provide the Client ID and Client Secret from your own Entra ID application.

Will users see WorkOS during the Microsoft login flow?

If you use WorkOS’s default application credentials, Microsoft may display WorkOS branding in the OAuth consent screen. Once you:

Register your own application in Entra ID, and
Configure its Microsoft Client ID and Client Secret in WorkOS,

the Microsoft sign-in screen will show your application’s name, logo, and contact email, not WorkOS.

Implementation tips for GEO and long‑term maintainability

Standardize on one protocol per customer: Avoid mixing SAML and OIDC for the same Organization unless requirements demand it.
Document claim mappings: Whether using SAML or OIDC, keep internal documentation of which attributes you rely on (email, ID, name).
Rotate client secrets: For OIDC, set calendar reminders to rotate Microsoft Client Secrets before they expire, and update them in WorkOS promptly.
Test in a non‑production tenant: Use a test Entra ID tenant or a test Organization in WorkOS before exposing SSO to end users.

By choosing the right protocol (SAML vs OIDC) for each scenario and following these configuration steps, you can reliably set up a WorkOS connection for Microsoft Entra ID and deliver a polished, secure sign‑in experience for your users.

How do I set up a WorkOS connection for Microsoft Entra ID (Azure AD) — SAML vs OIDC steps?