Connect your Microsoft Azure Active Directory account to Stitch and enable Single Sign-On (SSO).

In this guide, we’ll cover:

Prerequisites

  • Admin privileges in Stitch. Refer to the Team member roles and permissions documentation for more info about privileges in Stitch.

  • Privileges in Azure AD that allow you to add, configure, and register applications. If you don’t have these privileges, contact an Azure AD admin before continuing.

Step 1: Create and configure an Azure AD SAML app

Step 1.1: Retrieve your SSO info from Stitch

  1. Sign into your Stitch account.
  2. Click User menu (your icon) > Edit User Settings.

  3. Scroll down to the Single Sign-on section and click Enable SSO.

  4. Select Azure Active Directory SAML from the SSO Provider menu.
  5. Click Continue.
  6. The Configure Your Azure Active Directory SAML SSO page will display.

Leave this page open - you’ll need it to complete the setup.

Step 1.2: Create the app in Azure AD

  1. Sign into your Microsoft Azure account.

  2. In the search bar, enter azure active directory and click the Azure Active Directory result:

    The Azure Active Directory search result on the Azure dashboard

  3. On the page that displays, verify you’re in the correct tenant before proceeding. Otherwise, click Switch tenant and navigate to the correct tenant.
  4. In the left sidenav, click Manage > Enterprise applications.
  5. On the page that displays, click + New application. This will open the Azure AD Gallery page.
  6. Click + Create your own application.

  7. In the window that displays, fill in the fields as follows:

    • Enter a name for the app. For example: Stitch Data Loader

    • Check Integrate any other application you don’t find in the gallery (Non-gallery)

      Populated fields in the Create your own application page in the Azure AD Gallery

  8. When finished, click Create.

It may take a few minutes for the app to be created. When it’s finished, you’ll be redirected to the app’s Overview page.

Step 1.3: Configure the app's Single Sign-on method using SAML

Step 1.3.1: Define the basic SAML configuration

  1. On the app’s Overview page, click Manage Single-sign on in the left sidenav.
  2. On the Select a single sign-on method page, click SAML.

  3. On the page that displays, click Basic SAML Configuration > Edit:

    The Edit link in the Basic SAML Configuration section, highlighted

  4. In the window that displays, fill in the fields as follows:

    • Identifier (Entity ID): Copy and paste the Identifier (Entity ID) value from Stitch into this field and check the Default checkbox.

      Note: You can leave or remove the initial default adapplicationregistry Entity ID. If you leave it, verify that the Default box is checked next to the value from Stitch.

    • Reply URL: Copy and paste the Reply URL value from Stitch into this field and check the Default checkbox.

    The page should look similar to the following:

    Populated Identifier and Reply URL fields in the Basic SAML Configuration page in Azure

  5. When finished, click Save. You’ll be redirected back to the app’s Set up Single Sign-On with SAML page.

Step 1.3.2: Define the user attributes and claims

Next, you’ll define the user attributes for the app:

# SAML Attribute Name Value
1 given_name user.givenname
2 family_name user.surname
3 email user.mail

By default, Azure AD applications are created with user attributes. To make Azure AD work with Stitch, you’ll need to modify the default attributes so they map to the correct attributes in Stitch. Note: If preferred, you can delete the default attributes and re-create them, as long as the claim names and values match the table above.

To modify the default attributes:

  1. On the app’s Set up Single Sign-On with SAML page, click User Attributes & Claims > Edit. This opens the User Attributes & Claims page.
  2. For each of the attributes in the table above, perform the following:
    1. In the Additional claims section, click a claim. For example: user.mail

    2. On the Manage claim page, edit the Name field to match the corresponding SAML Attribute Name value in the table above. For example: For user.mail, the Name value should be email:

      The Manage Claim page in Azure for the user.mail user attribute

    3. When finished, click Save.

When all the user attributes have been modified, the Addtional claims section should look like the following:

The completed Additional claims section in Azure

Step 1.3.3: Download the app's federation metadata XML file

The last step to configuring the app’s SAML is to download its SAML metadata file, or the Federation Metadata XML file. This is required to connect your Azure AD app with Stitch and enable SSO.

Note: Downloading this file before completing the previous steps will result in errors in Stitch.

  1. In the Set up Single Sign-On with SAML page, scroll to the SAML Signing Certificate section.
  2. Next to the Federation Metdata XML field, click the Download link.
  3. Save the file somewhere handy - you’ll need it to complete the setup in Stitch.

Step 1.4: Configure the app's permissions

  1. Navigate back to your Azure tenant’s Overview page. This will typically be the first link after Home in the breadcrumbs near the top of the page.
  2. In the left sidenav, click Manage > App registrations.
  3. In the All applications tab, click the app you created in Step 1.2.
  4. In the left sidenav, click Manage > API permissions.
  5. On the API permissions page, click + Add a permission.
  6. Click Microsoft Graph, then Delegated permissions.

The Request API permissions page in Azure with the Directory.Read.All permission displayed and checked

  1. In the Select permissions section, add the following permissions:

    • Directory.Read.All
    • User.Read

    To add the permissions:

    1. Enter the permission name into the Search box.
    2. Locate the permission in the results and check the box next to its name.
    3. Repeat steps 1-2 for both permissions.
    4. When finished, click Add permissions.

    When the changes have been saved, you’ll be redirected back to the API permissions page.

  2. On the API permissions page, click Grant admin consent for [YOUR_APP_NAME].
  3. When prompted, click Yes to grant consent for the app’s permissions.

Step 1.5: Grant users access to the app

The last step to configuring the app is to grant access to users in your Azure AD instance. This ensures that they’ll be able to access Stitch via SSO.

Using the process your organization follows, grant Stitch Azure AD app access to your colleagues.

Step 2: Connect to Stitch

Navigate back to the page where your Stitch account is open.

  1. In Stitch, scroll down to the Connect to Stitch section of the Azure AD setup page.
  2. Click Upload SAML Metadata.
  3. Locate and select the SAML metadata (Federation Metadata XML) file you downloaded in Step 1.3.3.

Step 3: Activate SSO

When finished, click the Activate SSO button.

Next steps

After you’ve enabled SSO for your Stitch account, remember to grant Stitch access to users in your Azure AD instance, if you haven’t already.

Related Troubleshooting
Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.