Microsoft Entra ID Import
On this page
The Microsoft Entra ID import is one of the integrations supplied with Alloy Navigator. It is delivered as workflow configuration, not as separate program code: a category of workflow parameters that holds its settings and credentials, and a scheduled task that connects to Microsoft Entra ID.
This page describes what a new 2026.1 database created with the Default Workflow contains; see Default Workflow Configuration. An upgraded database need not contain the integration, and an administrator may have changed it.
The scheduled task Microsoft Azure AD Integration imports users from Microsoft Entra ID through Microsoft Graph. It creates and updates persons and creates organizations.
This integration is separate from the built-in Active Directory import; see Active Directory Synchronization.
What is included
- Settings page. The integration has its own page in Workflow Configuration, Integrations > Microsoft Azure AD, with twelve workflow parameters. They include the tenant and client ID and the secret, the handling of disabled accounts, the user types to import, e-mail matching, photo download, location creation, and Safe Mode.
- Credentials. You enter the integration's client ID and client secret as parameter values on that page. Both are workflow parameters of the encrypted type, and their values are held in the workflow parameter store, not in the credential storage used for accounts or mail profiles. When you save them on the Workflow Configuration page of the Settings App, the Settings App stores them encrypted. Treat an exported workflow file as sensitive: Alloy Navigator can decrypt the encrypted values it contains.
- Scheduled task. One scheduled task, Microsoft Azure AD Integration, runs the import, carried out by the Scheduled Task Agent. Scheduled tasks in general are described in Scheduled Tasks.
- Connection. The import reaches Microsoft at
graph.microsoft.comandlogin.microsoftonline.com. - Safe Mode. The integration has a Safe Mode parameter. With Safe Mode on, the job runs and produces a session log, but no data is added or modified. With Safe Mode Off, the job adds and modifies data.
- Debug logging. The integration has a debug logging switch.
The import is available both on-premises and in Alloy Navigator Cloud; see Administering Alloy Navigator Cloud.
The task and Safe Mode in the supplied configuration
- The Microsoft Azure AD Integration task is disabled in the supplied configuration, so it makes no call to Microsoft until an administrator supplies the credentials and enables it.
- Safe Mode is set to Safe Mode Off in the supplied configuration. Unless you change it, the first run after you enable the task adds and modifies data.
Prerequisites
To change the integration's settings, you need:
- In the Settings App, the administrative right that allows managing Workflow Configuration; see Permissions Reference.
- In the Admin Center, the Workflow Configuration permission. The Admin Center shows its Workflow Configuration entry only to holders of this permission.
To enable and run the task, you also need the right that gives access to Scheduled Tasks in the application you use; see Scheduled Tasks.
In Microsoft Entra ID, you need an account that can register applications and grant admin consent for Microsoft Graph application permissions. Microsoft lists the roles that can grant this consent in Grant tenant-wide admin consent to an application.
Prepare Microsoft Entra ID
The import connects to Microsoft Graph as an application registered in your Microsoft Entra tenant, with an application permission of its own. Before you enable the import, register this application and collect three values for the integration's settings page: the tenant ID, the client ID, and the client secret.
- In the Microsoft Entra admin center of the tenant whose users you want to import, go to App registrations and register a new application. For the procedure, see Microsoft's Register an application in Microsoft Entra ID.
- On the application's Overview page, copy the Application (client) ID. You enter it as the client ID.
- Copy your tenant ID, which Microsoft Entra ID shows under Overview > Properties; see How to find your tenant ID. You enter it as the tenant ID.
- On the application's API permissions page, select Add a
permission > Microsoft Graph > Application permissions, and
add the
User.Read.Allpermission. - On the same page, select Grant admin consent for your tenant. Microsoft Graph application permissions always require admin consent; see Get access without a user.
- On the application's Certificates & secrets page, select Client secrets > New client secret, choose an expiration, and select Add. Copy the secret's Value right away: Microsoft does not show it again after you leave the page. You enter it as the client secret. See Add and manage app credentials in Microsoft Entra ID.
A client secret is valid for 24 months or less. Before it expires, create a new client secret for the application and enter it as the client secret on the integration's settings page.
In the Settings App
Enable the import
Before enabling the schedule, test the import in Safe Mode.
- Open Workflow and Business Logic > Workflow Configuration.
- In the category tree, select Integrations > Microsoft Azure AD. The right pane shows one input control for each parameter, with its description.
- Enter the tenant ID, the client ID, and the client secret that you copied in Microsoft Entra ID, and fill in the integration's other settings; see Import settings.
- Set Safe Mode. With Safe Mode Off, the job adds and modifies data.
- Click Save on the Standard toolbar. Save writes the changed values of the selected category.
- Go to Services > Scheduled Tasks > Tasks and select the Microsoft Azure AD Integration task.
- Click Enable. To run the task, click Run.
In the Admin Center
Enable the import
Before enabling the schedule, test the import in Safe Mode.
- Open Workflow and Business Logic > Workflow Configuration.
- In the category tree, open Integrations > Microsoft Azure AD. The page shows one control for each parameter.
- Enter the tenant ID, the client ID, and the client secret that you copied in Microsoft Entra ID, fill in the integration's other settings, and set Safe Mode; see Import settings.
- Click Save. Save and Cancel appear once you change a field. If you leave the page with unsaved changes, the Admin Center asks: You should save you changes before leaving this page. Do you want to leave this page?
- In the Scheduled Tasks area, on the Tasks tab, find the Microsoft Azure AD Integration task. The Enabled column shows whether the task is enabled.
- Enable the task. How to enable and run a task in the Admin Center is described in Scheduled Tasks.
To read the task's sessions, click Microsoft Azure AD Integration on the Tasks tab. The task opens with a Settings tab and a Sessions tab, where you read the task's sessions. If no Automation Server is active, the opened task shows the warning Warning. For this job to be executed, the Automation Server must be set up and running.
On the Workflow Configuration page of both applications you change only the parameter values; the set of parameters itself is defined in the Settings App. For how the two applications relate, see Admin Center and Settings App, and for workflow parameters in general, see Workflow Overview.
Test the import before enabling its schedule
Safe Mode is off in the Default Workflow. Before a first run:
- In Workflow Configuration > Integrations > Microsoft Azure AD, set Safe Mode to Safe Mode On and save your changes.
- Run Microsoft Azure AD Integration manually and review its session log; see Scheduled Tasks. The run produces a log without adding or modifying data.
- When the results are as expected, set Safe Mode to Safe Mode Off, save, and enable the task's schedule. Later runs add and modify data.
Import settings
These settings apply to the supplied integration. Set them under Workflow Configuration > Integrations > Microsoft Azure AD in either administration application.
Organizational Structure
Choose how Entra companies and departments map to organizations:
| Value | Organization structure |
|---|---|
| Company Name\Department Name | Companies are parent organizations, with departments beneath them. If a user has only a company or only a department, that organization is placed at the top level. |
| Company Name | A flat list of companies. |
| Department Name | A flat list of departments. This is the supplied setting. |
The integration assigns the Company or Department category when it creates an organization or finds one whose category is empty. It preserves an existing nonempty category.
Disabled Account Handling
For an existing Person whose Entra account is disabled, choose Mark Person Disabled or Mark Person Inactive. The supplied setting is Mark Person Inactive. A disabled Entra account that matches no Person is not created.
On a later import, an enabled Entra account sets its matched Person to Active, including a Person previously marked Inactive. Do not use Mark Person Inactive to prevent the integration from reactivating that Person after the Entra account is enabled again.
E-mail Matching Field Usage
The integration first looks for the Person linked to the Entra user's previous import. If no link is found, it compares the Person's Primary E-mail Address with the selected Entra value:
- emailAddress, the supplied setting, uses the user's
mailvalue. - userPrincipalName uses the user's UPN, which can differ from their e-mail address.
The selected value is also written to the Person's Primary E-mail Address when the Person is created or updated.