Integrations

Microsoft Azure AD integration

Introduced in 2022.2

Updated in 2023.1

Integration with Microsoft Azure AD is a pre-built workflow package that keeps Alloy Navigator 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.

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

  • Other workflow items and components that make that scheduled task work

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, 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. Enable 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.

Configure Microsoft Azure AD integration in Alloy Navigator

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 Workflow and Business Logic > 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 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..

      • 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 the Debug Logging Status is turned on, the integration records a lot more information in the logs to aid in troubleshooting.

      • Safe Mode - when the Sate Mode is 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 your Microsoft Azure AD integration

We recommend that you first turn the Safe Mode on and test the integration in the safe mode, without creating any records. You will need your Admin Center or Settings App for this.

NOTE: Make sure that the Automation Server is running. In the Settings App, you can do this by checking the status of the Automation Server icon in the App status bar.

  1. Under Workflow and Business Logic > Workflow Configuration > Integrations > Microsoft Azure AD, turn the Safe Mode on.

  2. Go to Services > Scheduled Tasks, select the Microsoft Azure AD Integration task, and click Run on the Module menu.

    If the Run command is unavailable, make sure that the integration is enabled, Microsoft credentials are provided, and the Automation Server is set-up and running. You may need click Refresh to refresh the information.

  3. To verify whether the task would run as expected, double-click the task, go to the Sessions tab, and review the entry at the top. You can also view the log under Services > Scheduled Tasks > Logs.

Enable the Microsoft Azure AD integration scheduled task

If everything works as expected, you can automate and schedule your Microsoft Azure AD integration. You will need your Admin Center or Settings App for this.

  1. Go to Services > Scheduled Tasks and double-click the Microsoft Azure AD Integration task to reveal ts details.

    TIP: In the desktop Setting App, you can press CTRL+G and enter 2908 (the task's ID) for quick access.

  2. Review the default schedule and customize it, if needed.

  3. Select the Enabled check box above Schedule and click OK to close the window.

IMPORTANT: Scheduled tasks require that the Automation Server is set-up and running. For details, see Settings and Tools Help: Configuring the Automation Server.