# Entra ID SAML (formerly Azure AD) ## Introduction Each SSO Identity Provider requires specific information to create and configure a new [Connection](https://workos.com/docs/glossary/connection). And often, the information required to create a Connection will differ by Identity Provider. To create an Entra ID SAML Connection, you'll need the Identity Provider Metadata URL that is available from the organization's Entra ID instance. *** ## What WorkOS Provides WorkOS provides the [ACS URL](https://workos.com/docs/glossary/acs-url) and [IdP URI (Entity ID)](https://workos.com/docs/glossary/idp-uri-entity-id). It's readily available in your Connection Settings in the [WorkOS Dashboard](https://dashboard.workos.com/get-started).  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:  The [Entity ID](https://workos.com/docs/glossary/idp-uri-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:  *** ## What you'll need 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 Entra admin dashboard. Here's how to obtain them: *** ## (1) Log in Log in to the [Entra ID Active Directory Admin dashboard](https://portal.azure.com/). Select "Enterprise Applications" from the list of Entra services.  *** ## (2) Select or create your application If your application is already created, select it from the list of Enterprise applications and move to Step 7.  If you haven't created a SAML Application in Entra, select "New Application".  *** ## (3) Initial SAML Application Setup 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".  Select "Single Sign-On" from the "Manage" section in the left sidebar navigation menu, and then "SAML".  *** ## (4) Configure SAML Application Click the Edit icon in the top right corner of the first step "Basic SAML Configuration".  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)".  *** ## (5) Configure User Attributes and Claims Click the Edit icon in the top right corner of the second step "Attributes & Claims".  Make sure the following attribute mapping is set: - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` → `user.mail` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` → `user.givenname` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` → `user.userprincipalname` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` → `user.surname` Below is an example of how to format your claim within the Entra claim editor. Make sure the 'Namespace' value ends in `/claims`.   ### Role Assignment (optional) With [identity provider role assignment](https://workos.com/docs/sso/identity-provider-role-assignment), users can receive roles within your application based on the group memberships Entra ID includes in their SAML assertion. 1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to **Entra ID → Enterprise apps → All applications** and select your SAML application. Open **Single sign-on → SAML**, then select **Edit** in **Attributes & Claims**. 2. Under **Additional claims**, select the existing group claim to edit it. If no group claim is configured, select **Add a group claim**. Entra ID makes the add option unavailable once a group claim exists. 3. Select **Groups assigned to the application** to send only groups relevant to this application. Group assignment requires [Microsoft Entra ID P1 or P2](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal). If group assignment isn't available, **Security groups** can emit the user's security group memberships, but includes groups beyond this application and is subject to the SAML group limit below. **Directory roles** does not emit a groups claim. 4. Set **Source attribute** to **Group ID** so the claim contains each group's immutable object ID. Keep the default claim name, `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`, and leave **Emit groups as role claims** unchecked. Select **Save**. 5. If you selected **Groups assigned to the application**, open the application's **Users and groups → Add user/group** and assign each group you want to use for role mapping, as described in [Step 6](#6-add-users-to-saml-application). The user must be a **direct member** of an assigned group; nested memberships are not included. Assigning only the user to the application does **not** assign their groups or cause those groups to be emitted. 6. On the SSO connection page in the [WorkOS Dashboard](https://dashboard.workos.com/), create SSO groups using the same Entra group object IDs as the **IdP Group ID**, then assign the intended WorkOS roles. Do not use group display names when the claim emits group IDs. > **Warning:** Missing or incorrect group claims can result in missing or wrong WorkOS role assignments, including falling back to the [default role](https://workos.com/docs/rbac/configuration/configure-roles/default-role) when no group mapping matches. Entra ID omits the group list when it exceeds the **150-group SAML limit**. Restrict claims to the groups needed by the application. Before rolling out the connection, test SSO with representative users, including one with no mapped group. Verify that the SAML assertion contains the expected group object IDs and that the [SSO profile](https://workos.com/docs/reference/sso/profile) returned by WorkOS has the expected role or roles. Repeat the sign-in after changing group membership or claim settings; SSO role assignment is calculated at sign-in. For Microsoft's configuration steps, options, and limitations, see [Configure group claims for applications by using Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims). *** ## (6) Add Users to SAML Application 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.  Select "Add user/group" from the top menu.  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".  Select "Assign" to add the selected users and groups of users to your SAML application.  *** ## (7) Obtain Identity Provider Details 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".  Next, within your connection settings under "Identity Provider Configuration", select "Edit Configuration" and enter the Entra metadata URL.   Your Connection will then be verified and good to go!