Connect Azure AD
Learn how to configure a connection to Azure Active Directory (AD) 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 an Azure Active Directory SAML Connection, you'll need four pieces of information: an ACS URL, an Identity Provider Issuer (also known as an Entity ID), an Identity Provider SSO URL, and an X.509 Certificate.
- ACS URL
- Identity Provider Issuer (Entity ID)
- Identity Provider SSO URL
- X.509 Certificate
WorkOS provides both the ACS URL, and Entity ID. They're both readily available in your Connection's Settings in the Developer Dashboard.
The ACS URL is the location an IdP 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 to that WorkOS will be the party performing SAML assertions via 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:
And then, you provide the Identity Provider SSO URL, as well as the X.509 Certificate.
The Identity Provider SSO URL is your application's login endpoint.
When your Enterprise customer's users follow this URL, we redirect them to your application that's associated with the Enterprise's specific Azure AD instance for authentication and sign in. Azure AD also uses this URL to start your application from the Office 365 Dashboard or Azure AD Admin Center.
Note: Azure Active Directory will refer to the Identity Provider SSO URL as a "Login URL" in their Admin Center.
For SAML, the Identity Provider SSO URL usually takes a form similar to this example:
Normally, the X.509 Certificate will come from your Enterprise customer's IT Management team when they set up your application's SSO in their Azure Active Directory admin center. But, should that not be the case during your setup, here's how to obtain it.
Note: Azure Active Directory will refer to the X.509 Certificate with the broad label "Signing Certificate" in their documentation.
Log in to the Azure Active Directory Admin Center Dashboard. Select "Find an enterprise application" located in the right hand section labelled "Quick tasks".
Select your application from the list of Enterprise applications.
Select "Single sign-on" from the "Manage" section found in the navigation menu.
Copy and Paste the "Login URL" into your Connection's Identify Provider Single Sign-On URL field in your WorkOS Developer Dashboard.
In the "SAML Signing Certificate" section, select "Download" for the Base64 Certificate, and save it to your preferred directory.
Finally, upload the Certificate in your WorkOS Connection Settings. Your Connection will then be verified and good to go!