How to connect to Microsoft Entra ID (Azure Active Directory)

Connecting is a single authorization in Apideck Vault: you sign in with your Microsoft work account, approve the directory permissions, and the connection is live. The application owner has already registered the Microsoft Entra app and configured its credentials, so nothing needs to be built or registered on your side. What you are doing is authorizing that app to read your own Microsoft Entra tenant.

The one thing worth arranging before you start is administrator consent. The permissions this connector needs are directory-wide permissions that Microsoft reserves for administrators, so the authorization is either completed by an administrator or pre-approved by one. Sort that out first and the rest is a two-minute job.

Microsoft renamed Azure Active Directory to Microsoft Entra ID in 2023. Both names refer to the same product, and the connector is still identified as azure-active-directory.

Prerequisites

• A Microsoft work or school account in the tenant you want to connect. A personal Microsoft account has no organizational directory behind it and cannot be used.

• Administrator consent for the directory permissions, arranged in one of two ways:

  • You complete the authorization yourself while signed in as an administrator who is allowed to consent on behalf of the organization (Microsoft lists Privileged Role Administrator, and Cloud Application Administrator or Application Administrator, in Grant tenant-wide admin consent to an application), or
  • an administrator grants consent for the tenant in advance, after which any permitted user can complete the authorization in Vault.

  Microsoft's default is to require administrator approval for these permissions. A tenant can relax its user-consent policy, so an ordinary user may occasionally get through, but plan the connection around an administrator either way.

What the connection asks for

The authorization screen lists the Microsoft Graph permissions below. All of them are read permissions: the connector reads from your directory and writes nothing back to it.

Permission	What it is used for
User.Read.All	Employee profiles, including the fields that only appear on the full user record
User.ReadBasic.All	Basic user details
Group.Read.All	Departments, which are read from Microsoft Entra groups
openid, offline_access	Sign-in, and keeping the connection alive without asking you to authorize again

Group.Read.All is what makes departments work. If it is not consented, the rest of the connection still works, but department requests fail with an authorization error.

Steps

1. In Vault, select the Azure Active Directory connector.
2. Click Authorize. You are redirected to the Microsoft sign-in page at login.microsoftonline.com.
3. Sign in with your Microsoft work or school account. The account you sign in with decides which tenant is connected, so if you have access to more than one organization, check that you are using the account for the tenant you intend to connect. Microsoft reuses an existing browser session, so use a private or incognito window if you were recently signed in as someone else.
4. Review the requested permissions and approve them. If you are signed in as an administrator, Microsoft also offers to consent on behalf of your organization: choosing that grants the permissions tenant-wide, so colleagues connecting later are not prompted individually.
5. You are returned to Vault and the connection shows as connected.
6. Optionally set the Timezone setting (see below), then save.

The Timezone setting

The connection has one optional setting, Timezone, and it is worth setting even though nothing fails if you skip it.

Microsoft Entra records dates such as an employee's hire date as midnight in your organization's own timezone, and then returns them in UTC. For any organization not on UTC, midnight local time falls on a different calendar day in UTC, so a hire date can arrive a day earlier or later than the date actually recorded. Selecting the IANA timezone your organization's directory data is maintained in (for example Europe/Brussels or America/New_York) lets the connector convert those dates back to the day your directory intends.

If your organization spans several timezones, choose the one the directory records are entered in rather than the one any individual employee sits in.

What you will see: a directory, not an HR system

Microsoft Entra ID is an identity directory, and this connector reads employees, their direct reports, and departments from it. That makes it an excellent source for who works here, who reports to whom, and how people are grouped.

It is not a source for HR data that a directory does not hold. Compensation, employment history and similar HR records do not exist in Entra at all, and the fields that can exist (job title, department, manager, hire date) come through only as completely as your organization maintains them in each user profile. If a field arrives empty, the usual explanation is that the profile does not carry it: adding it to the profile in Microsoft Entra is what makes it available here. Where the directory is not the system of record for that information, connect the HR system that is.

Troubleshooting

What you see	What it usually means and what to do
AADSTS700016: the application was not found in the directory or tenant	The app is not present in your tenant, has never been consented to, or the request reached the wrong tenant. Confirm with the application owner which app is being used, check that you signed in with an account in the intended tenant, and have an administrator grant consent.
AADSTS65001: the user or administrator has not consented	Consent has never been granted for these permissions in your tenant. An administrator needs to approve it, either during the authorization or in advance via Grant tenant-wide admin consent.
AADSTS90094: administrator consent is required	You do not have permission to consent yourself. Microsoft's prompt can forward the request to your administrator; alternatively ask an administrator to complete the authorization.
Authorization succeeds, but the directory looks like the wrong organization	You signed in with an account from another tenant. Sign out of Microsoft, or retry in a private window, and use the account belonging to the tenant you want.
Department requests fail with an authorization error	Group.Read.All was not consented. Have an administrator grant it, then reconnect.
A working connection stops after a long period of inactivity	Microsoft's refresh tokens expire after 90 days without use, so a connection that has been idle that long needs to be authorized again in Vault.
Hire dates are one day out	The Timezone setting is unset or set to the wrong zone. Update it and re-read the affected records.

Microsoft documents every code above in its authentication and authorization error codes reference, and administrators can review or revoke what has been consented in the Microsoft Entra admin center under Enterprise applications.

If the connection still will not complete after the checks above, contact Apideck Support with the exact AADSTS code from the Microsoft error screen.