Set up an Azure Active Directory SAML Connection

Stytch's Single Sign On (SSO) product allows your customers to log into your application via third party Identity Providers, like Azure Active Directory (Azure AD). In this guide, you'll learn how to configure an Azure AD SAML SSO connection, which is something that your customers will need to complete before their team members will be able to log into your application via SSO.

By the end of this guide, you'll have:

  • a new Azure AD SAML Connection that is fully configured and ready for use.
  • a new Azure AD application that can be used to provision access to your application.
  • a Stytch B2B implementation that can use SSO for authentication.

Before you start

  • Create a Stytch B2B project via the Stytch Dashboard if you don't have one already. To do so, click on your existing project name in top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
  • Copy your project_id and secret from the Test environment tab in the API keys section of the Stytch Dashboard. You'll need to include these values in every backend Stytch API call.
  • Create a new Organization by calling our Create an Organization endpoint:
curl --request POST \
	--url https://test.stytch.com/v1/b2b/organizations \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_name": "Example Org Inc.",
		"organization_slug": "example-org"
	}'

Step 1: Create a new SAML connection

Call our Create SAML Connection endpoint in order to create a new SAML Connection. Include the organization_id that you'd like the Connection to belong to and a display_name for the Connection like "Azure AD".

curl --request POST \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
	  "display_name": "Azure AD"
	}'

Save the acs_url, audience_uri, and connection_id values from the connection object in the Create SAML connection response for use in Step 2, where you'll use those values to configure a new Azure AD Application, and later in Step 4.

Step 2: Create and configure a new Azure AD application

  1. Log into portal.azure.com and select the Azure Active Directory service:

    Azure Active Directory button in Azure

  2. Navigate to the Enterprise applications tab:

    Enterprise applications tab in Azure

  3. Click New application:

    New application button in Azure

  4. Click Create your own application:

    Create your own application button in Azure

  5. Input the name of your application, select Integrate any other application you don't find in the gallery (Non-gallery) and then click Create.

  6. Once your application has been created, select Set up single sign on:

    Set up single sign on button in Azure

  7. When prompted to Select a single sign-on method, choose SAML.

  8. Click Edit next to Basic SAML Configuration and add the following values:

    • Identifier (Entity ID): Add the audience_uri value from your Stytch connection object.
    • Reply URL (Assertion Consumer Service URL): Add the acs_url value from your Stytch connection object.
    • For the purposes of this guide, you do not need to add any Sign on URL, Relay State, or Logout Url values.

  9. Save your Basic SAML Configuration and then click Edit next to Attributes & Claims. Make the following changes:

    • Click the claim called Unique User Identifier (Name ID) and change the Source attribute value to user.primaryauthoritativeemail.
    • Delete the claims under Additional claims and create the following two claims instead:

      1. Name: firstName; Source: Attribute; Source attribute: user.givenname
      2. Name: lastName; Source: Attribute; Source attribute: user.surname

Now that you've created and configured a new Azure AD application, you're ready to update the SSO Connection from Step 1 with additional data surfaced by Azure AD.

Step 3: Retrieve values from Azure AD to configure your SAML Connection

You'll now need a few additional values from Azure AD in order to finish configuring your Stytch SAML Connection.

In the Single sign-on tab of your Azure AD application, scroll down to the SAML Certificates section and click Download next to Certificate (Base64):

Download certificate button in Azure

Open the downloaded .cer file in a text editor, and copy the plaintext certificate value (including the BEGIN_CERTIFICATE and END_CERTIFICATE lines) for use in Step 4. Note that you'll need to replace the newlines in the certificate value with \n characters before you include the certificate value in a cURL request.

Next, scroll to the Set up [application name] section and copy the Login URL and Azure AD Identifier values:

Login URL and Azure AD Identifier values in Azure

Step 4: Call the Update SAML Connection endpoint

In addition to the information from Azure AD in Step 3, you'll also need these parameters in order to call our Update SAML Connection endpoint:

  • the organization_id and connection_id from Step 1.
  • an attribute_mapping object with the following structure.
    "attribute_mapping": {
	"email": "NameID",
	"first_name": "firstName",
	"last_name": "lastName"
},

With all the necessary data, your Update SAML Connection API request should look like this:

curl --request PUT \
	--url https://test.stytch.com/v1/b2b/sso/saml/{ORGANIZATION_ID}/connections/{CONNECTION_ID} \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"idp_entity_id": "{AZURE_ID_IDENTIFIER}",
		"idp_sso_url": "{LOGIN_URL}",
		"x509_certificate": "{SAML_CERTIFICATE}",
        "attribute_mapping": {
		  "email": "NameID",
		  "first_name": "firstName",
		  "last_name": "lastName"
		}
	}'

After a successful Stytch API call, both your Azure AD application and your SAML Connection are now fully configured. The only remaining step is to provision access.

Step 5: Provision access to your application

In the Users and groups tab in Azure AD, assign the application to team members who should have access to it by clicking Add user/group:

Add user/ group button in Azure

You should now be able to successfully complete an SSO login flow via our Start SSO login flow and Authenticate SSO login endpoints using your new Azure AD Connection!

What's next

Build a user interface that allows users to initiate the SSO login flow. You'll also need a page to handle the redirect back to your application at the end of the SSO flow.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also check out our interactive B2B demo app to see the app in action.