WorkOS Docs Homepage
Integrations
DashboardSign In

Entra ID SAML (formerly Azure AD)

Learn how to configure a connection Entra ID via SAML.

Each SSO Identity Provider requires specific information to create and configure a new Connection. And often, the information required to create a Connection will differ by Identity Provider.

To create a Entra ID SAML Connection, you’ll need the Identity Provider Metadata URL that is available from the organization's Entra ID instance.

WorkOS provides the ACS URL and IdP URI (Entity ID). It’s readily available in your Connection Settings in the WorkOS Dashboard.

A screenshot showing the ACS URL and Entity ID in the WorkOS dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. In Entra ID’s case, it needs to be set by the organization when configuring your application in their Entra ID instance.

Specifically, the ACS URL will need to be set as the “Reply URL (Assertion Consumer Service URL)” in the “Basic SAML Configuration” step of the Entra ID “Set up Single Sign-On with SAML” wizard:

A screenshot showing the location to place the WorkOS ACS URL in the Azure Dashboard.

The Entity ID is a URI used to identify the issuer of a SAML request, response, or assertion. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the organization's Entra ID instance.

Specifically, the Entity ID will need to be set as the “Identifier (Entity ID)” in the “Basic SAML Configuration” step of the Entra ID “Set up Single Sign-On with SAML” wizard:

A screenshot showing the location to place the WorkOS Entity ID in the Azure Dashboard.

In order to integrate you’ll need the Entra ID IdP Metadata URL.

Normally, this information will come from the organization's IT Management team when they set up your application’s SAML 2.0 configuration in their Azure admin dashboard. Here’s how to obtain them:

Log in to the Entra ID Active Directory Admin dashboard. Select “Enterprise Applications” from the list of Azure services.

A screenshot showing where to select "Enterprise Applications" in the Azure dashboard.

If your application is already created, select it from the list of Enterprise applications and move to Step 7.

A screenshot showing where to select an existing application in the Azure dashboard.

If you haven’t created a SAML Application in Azure, select “New Application”.

A screenshot showing where to select "New Application" in the Azure dashboard.

Select “Create your own application”, then enter a descriptive app name. Under “What are you looking to do with your application?”, select “Integrate any other application you don’t find in the gallery (Non-gallery)”, then select “Create”.

A screenshot showing where to input the name of the new application in the Azure dashboard.

Select “Single Sign-On” from the “Manage” section in the left sidebar navigation menu, and then “SAML”.

A screenshot showing how to select "SAML" as the single sign-on method of the Azure application in the Azure dashboard.

Click the Edit icon in the top right corner of the first step "Basic SAML Configuration".

A screenshot showing where to select "Edit" for the "Basic SAML Configuration" step in the Azure dashboard.

Input the IdP URI (Entity ID) from your WorkOS Dashboard as the “Identifier (Entity ID)”. Input the ACS URL from your WorkOS Dashboard as the “Reply URL (Assertion Consumer Service URL)”.

A screenshot showing where to input the WorkOS ACS URL and WorkOS Entity ID in the Azure dashboard.

Click the Edit icon in the top right corner of the second step "Attributes & Claims".

A screenshot showing where to select "Edit" for the "Attributes & Claims" step in the Azure dashboard.

Make sure the following attribute mapping is set:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mail
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameuser.givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameuser.userprincipalname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameuser.surname

Below is an example of how to format your claim within the Azure claim editor. Make sure the 'Namespace' value ends in /claims.

A screenshot showing the "Manage Claim" configuration in the Azure dashboard.
A screenshot showing the "Attribute & Claims" configuration in the Azure dashboard.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

Select "Add a group claim" from the top menu. Next, select which groups you'd like to return in the Group Claims settings. For example, in Entra ID, you could select "Groups assigned to the application" to only send groups assigned to the SAML app. Finally, select "Save" once finished configuring the groups.

A screenshot showing how to add a groups claim to your SAML app in the Azure dashboard.

In order for your users or groups of users to be authenticated, you will need to assign them to your Entra ID SAML application. Select “Users and groups” from the “Manage” section of the navigation menu.

A screenshot showing where to select "Users and groups" in the Azure dashboard.

Select “Add user/group” from the top menu.

A screenshot showing where to select "Add user/group" in the Azure dashboard.

Select “None selected” under the “Users and Groups”. In the menu, select the users and groups of users that you want to add to the SAML application, and click “Select”.

A screenshot showing where to select "None Selected" under "Users and Groups" and add a user in the Azure dashboard.

Select “Assign” to add the selected users and groups of users to your SAML application.

A screenshot showing where to select "Assign" in the Azure dashboard.

Select “Single Sign-On” from the “Manage” section in the left sidebar navigation menu.

Navigate down to Section 3 of the “Single Sign-On” page, to “SAML Signing Certificate”. Copy the url provided in “App Federation Metadata URL”.

A screenshot showing where to select the "App Federation Metadata URL" in the Azure dashboard.

Next, within your connection settings under "Identity Provider Configuration", select "Edit Medata Configuration" and enter the Azure metadata URL.

A screenshot showing where to select "Edit Metadata Configuration" on the "SSO Connection" page in the WorkOS dashboard.

Your Connection will then be verified and good to go!

A screenshot showing an active Azure SAML connection in the WorkOS dashboard.