How to set up an Azure Active Directory security provider

Audience: System administrators installing and configuring Sapho Server

If you want to integrate Sapho with Microsoft applications, such as Outlook, Teams, etc., you will need to properly configure your Azure Active Directory and set up an Azure Active Directory security provider in Sapho.

Register the app on the Azure Portal

  1. Go to your Azure Portal and sign in with an Admin account.
  2. In the portal menu, go to Azure Active Directory→ App Registration→ New App Registration.
  3. Create an app and select the Application type: Web App / API. This should point to your Sapho instance.
  4. Go to your app settings. You will need the Application ID for setting up Azure Active Directory as a security provider in Sapho Builder later.

    In the following steps, please be aware that you will need to click Save after each action.
  5. Create a key for the app and save the value for later (this will be used as your Client Secret). Go to Keys, add a new record, and enter a description in the Description field. The settings you put under Duration should comply with your security policy.
  6. Value is automatically generated when you save your record and will only be visible once the record is saved. Please copy your key value as you will need it during this setup and you will not be able to retrieve it later.
  7. (Optional) Go to Reply URLs to add additional Sapho server base URLs. This is only needed if you are going to use the app with multiple Sapho servers.
  8. Go to Required permissions to set up application permissions to access Azure Active Directory.
  9. In Required permissions, click +Add in the top left corner of the page. You will be taken through a setup wizard. Select the following options: Select an API → Microsoft Graph → Select.
  10. In the second setup wizard, click Select permissions to set up API permissions (Please note: this is only needed for Outlook).
    • Select the following Application Permissions:
    • Add the following Delegated Permissions:


    • Click Save.

How to set up Azure Active Directory as a security provider in Sapho Builder

Once you have finished configuring Azure Active Directory, you will need to sign in to Sapho Builder.

  1. Go to Security and add Azure Active Directory as a new security provider with the following settings:
    • Domain - the domain name that your Microsoft account runs on.
    • Application ID - the Application ID from step 4 above.
    • Client Secret - the key value you saved in step 5 from above.
  2. Once you have created a security provider, click SIGN IN WITH AZURE ACTIVE DIRECTORY on the security provider detail page. Log in with your admin account and click Accept to approve the permissions for Sapho.

    • Once you have approved the permissions, you will be taken back to the security provider detail page to set up which Azure Active Directory groups can access the Sapho Builder environment (optional).
  3. Go to Micro Apps with Access to select which micro apps will have access to Azure Active Directory. You will need to enable your Home App since it is used for bot authentication (bots are not bound to any app in Sapho and needs an app to authenticate against).

You should now be able to leverage your Azure Active Directory settings from right within Sapho.