Connect Azure AD

Learn how to configure a connection to Azure Active Directory (AD) via SAML

Introduction

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 Azure AD SAML Connection, you'll need the Identity Provider metadata Url that is available from your Enterprise customer's Azure AD instance.

WorkOS Provides

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

The ACS URL is the location an Identity Provider redirects its authentication response to. In Azure AD's case, it needs to be set by the Enterprise when configuring your application in their Azure AD 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 Azure AD "Set up Single Sign-On with SAML" wizard:

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 Enterprise's Azure AD instance.

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

Overview

And then you provide the Azure AD IdP Metadata URL.

Normally, this information will come from your Enterprise customer's IT Management team when they set up your application's SAML 2.0 configuration in their Azure admin dashboard. However, should that not be the case during your setup. Here's how to obtain them:

1

Log in

Log in to the Azure Active Directory Admin dashboard. Select "Enterprise Applications" from the list of Azure 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 Azure, 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.

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.

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
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 Azure AD 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, edit the Metadata Configuration and provide the Metadata URL you obtained from the Azure Dashboard.

Your Connection will then be verified and good to go!