Integrations

Microsoft Azure AD integration

Introduced in 2024.2

Integration with Microsoft Azure AD is a pre-built workflow package that keeps Alloy Navigator Express in sync with user information from your Azure Active Directory (AD). It regularly imports user data from the Azure AD, creates person records for new users, updates person records for existing users, associates persons with their organizations (departments) and creates new organization records when needed. This article describes how to enable the Microsoft Azure AD integration so you can use it.

How Microsoft Azure AD integration works

The integration runs as an automated scheduled task and performs the following operations:

  1. Imports user data from Azure AD.

  2. Creates person records for new users.

  3. Updates existing person records with the latest details.

  4. Associates persons with their organizations and creates new organization records when necessary.

Prerequisites: Obtain Azure credentials

Before you configure the integration, register a Microsoft Graph application in Azure and collect the following information: Tenan tID, Client ID, and Client Secret.

What does Microsoft Azure AD integration include?

The integration consists of the following workflow items and components:

  • Workflow parameters for quick customization

  • Workflow scheduled task "Microsoft Azure AD Integration" #2908

How to enable Microsoft Azure AD integration

Initially, the Microsoft Azure AD integration is disabled. To enable it, follow these steps:

  1. In your Azure portal, register a Microsoft Graph application and create a client secret.

  2. In Alloy Navigator Express, configure the integration. Namely, you must enable the integration, specify your tenant ID, and provide the client ID and client secret for the registered application. Other customizations are optional.

  3. Make sure your integration works as expected.

  4. Activate the automation by enabling the scheduled task.

All these steps are described in details below.

Register a Microsoft Graph application in Azure

In your Azure portal, register a new Microsoft Graph application and grant the registered application the User.ReadAll API application permission.

INFO: For instructions, see Register a Microsoft Graph application.

You will need this information from Azure:

  • Client ID: the Application (client) ID that uniquely identifies your registered Microsoft Graph application. It appears on the overview page when you register the application.

  • Client Secret: the client secret for your Microsoft Graph application to prove its identity when requesting a token. To create a client secret, under Manage, select Certificates & secrets and follow on-screen instructions.

  • Tenant ID: the tenant ID is the globally unique identifier (GUID) that identifies your organization in Microsoft 365.

Customize workflow configuration

Now configure the integration, i.e., assign values to workflow parameters. You will need your desktop Settings App or web-based Admin Center to complete this task.

  1. In Settings or Admin Center, go to Customization > Workflow Configuration > Integrations > Microsoft Azure AD.

  2. Provide your credentials from your Azure portal: Tenant ID, Client ID, and Client Secret. For details, see Register a Microsoft Graph application in Azure above.

  3. Other customizations are optional. To learn about every configuration parameter, see its description.

    1. Under Disabled Account Handling, choose which status to assign to person records in Alloy Navigator Express when their corresponding user accounts in Azure AD are disabled: "Disabled" or "Inactive."

      Disabled person records are automatically set back to the "Active" status when their status in the Azure AD changes. Person records in the "Inactive" status are permanently deactivated.

    2. Under Importable User Types, specify which types of Azure AD users to import: members, guests, or both.

      Typically, members are employees, while guests are external collaborators and customers.

    3. Under Email Matching Field Usage, specify which Azure AD attribute to use for matching with Primary Email Address values of person records in Alloy Navigator Express.

      • emailAddress: This attribute value is the Azure AD email address for user accounts

      • userPrincipalName (UPN): This attribute value is the Azure AD username for user accounts (for example, "someone@example.com")

      The UPN doesn't need to match the email address, though they typically match.

    4. You may want to test and troubleshoot your integration before the production use.

      • Debug Logging Status: When turned on, the integration records a lot more information in the logs to aid in troubleshooting.

      • Safe Mode: When turned on, the integration does not create any person records or make any changes, only keeps the logs.

      TIP: Use the Safe Mode in conjunction with the Debug Logging Status when issues arise. Logs are available under Services > Scheduled Tasks > Logs in Settings or Admin Center. The task name is Microsoft Azure AD Integration.

  4. Click Save to apply your changes.

Test in Safe Mode

We recommend that you first test the integration in the safe mode, without creating any records.

  1. In the Admin Center or Settings, under Customization > Workflow Configuration > Integrations > Microsoft Azure AD, make sure the Safe Mode checkbox is selected.

  2. Navigate to Services and Integrations > Scheduled Tasks. In the Settings App, the section name is Services > Scheduled Tasks.

  3. Locate the task named Microsoft Azure AD Integration.

  4. Select the task and click Run Now at the top.

  5. After the task succeeds, view the statistics to confirm it ran as expected.

    • In the Settings App, the session log is available right in the Scheduled Task window, on the Sessions tab.

    • In the Admin Center, go to Services and Integrations > Scheduled Tasks > Logs.

Enable automation

Once you’ve confirmed the integration works as expected, enable the automation:

  1. In the Admin Center or Settings, navigate to Services and Integrations > Scheduled Tasks. In the Settings App, the section name is Services > Scheduled Tasks.

  2. Open the task named Microsoft Azure AD Integration.

  3. Review the default schedule and adjust it, if needed. The schedule uses the server's local time.

    TIP: For optimal performance, we recommend running the task during off-peak hours when the server load is minimal.

  4. Select the Enabled checkbox to activate the scheduled task.

  5. Click OK to save the changes.

Now, the integration runs automatically according to your schedule.

Related Information:

Settings and Tools Help: Configuring the Automation Server

Tools and Utilities Help: Scheduled Task Agent