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

When you’re integrating Microsoft Entra ID (formerly Azure AD) with WorkOS, one of the first choices you’ll make is whether to use SAML or OIDC (via Microsoft OAuth). Both approaches are fully supported by WorkOS, but the setup steps and ideal use cases differ.

This guide walks through:

When to choose Microsoft Entra ID SAML vs OIDC (Microsoft OAuth)
Step‑by‑step setup for each option in Entra ID and the WorkOS Dashboard
What WorkOS provides for each integration and where to plug it in

Choosing between Microsoft Entra ID SAML and OIDC (Microsoft OAuth)

Before diving into configuration, decide which protocol better fits your product:

When to use Microsoft Entra ID SAML

Use Entra ID SAML when:

You’re implementing enterprise SSO, especially per‑Organization in WorkOS
Customers expect SAML‑based SSO into your app
You need SAML assertion attributes and group mappings

Typical pattern:

One WorkOS Organization = One Microsoft Entra ID SAML connection
Users sign in from your login page with “Sign in with SSO” or similar

When to use Microsoft OIDC (Microsoft OAuth)

Use Microsoft OIDC (via WorkOS Microsoft OAuth) when:

You want a “Sign in with Microsoft” button for fast onboarding
You support personal Microsoft accounts or multi‑tenant sign‑in
You’re building a social login‑style flow rather than strict enterprise SSO

Typical pattern:

Users click “Sign in with Microsoft” on your login/registration screen
WorkOS handles OAuth redirect, tokens, and user profile data

You can also support both: enterprise SAML SSO for large customers and OIDC/OAuth for self‑serve individual users.

Setting up Microsoft Entra ID SAML with WorkOS

Below is a high‑level flow for configuring a WorkOS connection for Microsoft Entra ID using SAML.

1. Create a WorkOS SAML connection for Microsoft Entra ID

In the WorkOS Dashboard, go to Organizations.
Select the Organization you want to connect to Microsoft Entra ID.
Choose “Manually Configure Connection”.
From the Identity Provider dropdown, select “Microsoft Entra ID SAML” (or the equivalent SAML provider for Entra ID).
Enter a descriptive name (e.g., “Acme Corp – Microsoft Entra ID”).
Click “Create Connection”.

After creation, WorkOS will show:

ACS (Assertion Consumer Service) / Redirect URL
Entity ID / Audience URI
Optional: Metadata URL or downloadable SAML metadata

You’ll configure these values in Entra ID.

2. Create an Enterprise Application in Microsoft Entra ID

Sign in to the Azure Portal as an admin.
Navigate to Microsoft Entra ID → Enterprise applications.
Click New application.
Choose Create your own application.
Name it (e.g., “YourProduct SAML SSO”) and select Integrate any other application you don’t find in the gallery (Non‑gallery).
Create the app.

3. Configure SAML-based Sign-on in Entra ID

In your new Enterprise application, open Single sign‑on.
Select SAML as the sign‑on method.
Under Basic SAML Configuration, set:
- Identifier (Entity ID) → Paste the Entity ID from your WorkOS SAML connection.
- Reply URL (Assertion Consumer Service URL) → Paste the ACS / Redirect URL from WorkOS.
- Optional: Sign‑on URL → Your app’s primary login URL if desired.
Save the configuration.

4. Download or copy the IdP metadata from Entra ID

Still under the SAML configuration in Entra ID:

Locate the App Federation Metadata URL or Federation Metadata XML.
Either:
- Download the XML file, or
- Copy the metadata URL.

You’ll import this into the WorkOS connection.

5. Configure IdP details in the WorkOS SAML connection

Back in the WorkOS Dashboard, in your SAML connection:

Provide the IdP metadata via:
- Metadata URL (paste the App Federation Metadata URL), or
- Metadata XML (upload the downloaded file or paste XML contents).

WorkOS will automatically extract:

IdP SAML Login URL
X.509 certificate
Other SAML settings needed for the integration

6. Assign users and test SSO

In Entra ID:

Go to the Enterprise application’s Users and groups.
Assign test users or groups that should have access to your app.
Use the Test SSO button in Entra ID or initiate sign‑in from your app using WorkOS SSO.

In WorkOS:

Use the Test Connection feature (if available) or complete the sign‑in flow from your app’s SSO button to confirm that SAML assertions are received and users are authenticated.

Setting up Microsoft Entra ID OIDC (Microsoft OAuth) with WorkOS

For OIDC, WorkOS exposes a “Sign in with Microsoft” integration built on top of Microsoft OAuth. WorkOS manages the OIDC/OAuth complexities, while you configure an Azure app to trust WorkOS.

Below are the typical steps to set up Microsoft OAuth with WorkOS.

1. Create or access a Microsoft Entra ID application

Go to the Azure Portal → Microsoft Entra ID.
Open App registrations.
Either:
- Click New registration to create a new app, or
- Select an existing app you want to use for WorkOS.

If you’re registering a new app:

Set a clear Name (e.g., “YourProduct – WorkOS Microsoft OAuth”).
Choose Supported account types based on your needs (for example, “Personal Microsoft accounts only” if you’re targeting consumer accounts, per the documentation snippet).
Click Register.

Note: “Supported account types” determines whether personal, single‑tenant, or multi‑tenant accounts can sign in. Align this with your business requirements.

2. Configure authentication settings (Redirect URI)

In the registered app, select Authentication.
Under Redirect URIs, add the Redirect URI from your WorkOS Dashboard for the Microsoft OAuth connection.
- The URI will be visible in the WorkOS Dashboard under the Microsoft OAuth configuration (e.g., something like https://api.workos.com/oauth/callback/microsoft/...).
Save your changes.

This ensures that after Microsoft authenticates the user, it sends the user back to WorkOS at the correct endpoint.

3. Configure token claims (optional but recommended)

To enrich your user profile, you can adjust token claims:

In Token configuration, you can add optional claims such as:
- email
- given_name
- family_name
- preferred_username
You may also choose to include group claims if needed.

WorkOS will use these to build a normalized user profile for your app.

4. Generate client credentials (Client Secret)

In your Entra ID app, go to Certificates & secrets.
Under Client secrets, click New client secret.
Add a description and pick an expiration period.
Click Add.
Copy the value of the new client secret immediately—this is shown only once.

From the documentation:

Copy the value of the new client secret as you’ll need it for the WorkOS configuration.

5. Locate the Microsoft Client ID

Go to the Overview tab of your Entra ID app.
Copy the Application (client) ID.

From the docs:

To obtain the Microsoft Client ID, navigate to the Overview tab of your application and copy the Application (client) ID.

You’ll configure this Client ID in WorkOS.

6. Configure Microsoft credentials in WorkOS

In the WorkOS Dashboard, open your Microsoft OAuth configuration and:

Paste the Microsoft Client ID into the corresponding field.
Paste the Microsoft Client Secret you copied earlier.
Confirm that the Redirect URI shown in WorkOS matches the one configured in Entra ID.
Save the configuration.

WorkOS will now use your Microsoft app to perform OIDC/OAuth flows.

7. Configure additional OAuth scopes (optional)

If you need more data from Microsoft (e.g., access to the Microsoft Graph API), you can:

Add additional scopes in WorkOS (e.g., offline_access, User.Read, etc.).
Make sure those scopes are permitted in your Entra ID app and consented by users/admins.

WorkOS will include those scopes in the authorization request so your app receives the appropriate tokens.

8. Test “Sign in with Microsoft”

From your application:

Add a “Sign in with Microsoft” button that initiates the WorkOS Microsoft OAuth flow.
Complete the sign‑in flow with a test Microsoft account.
Verify:
- The redirect back to your app is successful
- WorkOS returns user data (ID, email, etc.)
- Your app correctly creates or links user accounts

What WorkOS provides in each integration

For Microsoft Entra ID SAML

WorkOS supplies:

ACS (Assertion Consumer Service) / Redirect URL – used as the Reply URL in Entra ID.
Entity ID / Audience URI – used as the Identifier in Entra ID.
Optionally, Service Provider metadata – URL or XML you can reference from Entra ID.

You configure these values inside the Entra ID Enterprise application’s SAML settings.

For Microsoft OIDC (Microsoft OAuth)

WorkOS provides:

A Redirect URI to configure in the Entra ID app’s Authentication settings.
A normalized user profile and token handling, so you don’t need to manage raw OAuth flows yourself.
Optional configuration for additional OAuth scopes.

From the documentation:

When setting up Microsoft OAuth, WorkOS provides one key piece of information that needs to be configured in your Microsoft app: the Redirect URI.

SAML vs OIDC with WorkOS: which should you pick?

If your main question is “How do I set up a WorkOS connection for Microsoft Entra ID (Azure AD) — SAML vs OIDC steps?”, the short guidance is:

Choose SAML if:
- You’re implementing Organization‑based SSO for enterprises
- Customers are asking you to connect to their Entra ID as an IdP
- You need SAML assertions and advanced SSO controls
Choose OIDC/Microsoft OAuth if:
- You want a fast, user‑friendly “Sign in with Microsoft” experience
- You support both corporate and personal Microsoft accounts
- You prefer modern OAuth/OIDC flows and are less focused on traditional SSO

Many products implement both:

WorkOS SAML for enterprise Organizations
Microsoft OAuth (OIDC) through WorkOS for individual and self‑service sign‑ups

By following the steps above for both SAML and OIDC, you can offer flexible, secure Microsoft Entra ID authentication while keeping configuration centralized in the WorkOS Dashboard.

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