Apideck CLI: Query 200+ SaaS APIs from your terminal. No SDK needed. Read more

Apideck Documentation Page

Microsoft Entra – Configuration Guide

Service ID: azure-active-directory

Microsoft Entra formerly know as Azure Active Directory (Azure AD) is Microsoft’s cloud-based identity and access management service, which helps your employee's sign in and access resources in.

How to create an OAuth app in Microsoft Entra ID (formerly Azure Active Directory)

Microsoft renamed Azure Active Directory to Microsoft Entra ID in 2023 (rename details). The product, the app registration experience and the APIs are the same; only the name changed. Apideck's service ID stays azure-active-directory, which is what you will see in API paths and in the Apideck Dashboard.

This guide is for the application owner: you register one Microsoft Entra app, configure its client ID and secret once in the Apideck Dashboard, and every customer then connects their own Microsoft tenant to it. You do not need a partnership with Microsoft to do any of this.

Before you start, you'll need: a Microsoft work or school account in your own Entra tenant, holding the Application Administrator or Cloud Application Administrator role. Personal Microsoft accounts cannot register an app that can later be publisher verified.

1. Register your app

  1. Sign in to the Microsoft Entra admin centre.
  2. Go to Identity > Applications > App registrations and select New registration. Microsoft's Register an application quickstart walks the same screens with current screenshots if you want a visual reference.
  3. Fill in the registration form:
    • Name: the name your customers' users and administrators will see on the Microsoft consent screen. Use your company or product name.
    • Supported account types: select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). This is what makes the app usable by customers outside your own tenant. Do not include personal Microsoft accounts: this connector reads a directory of employees and groups, which only exists in a work or school tenant.
    • Redirect URI: set the platform to Web and enter the value in step 2 below, exactly.

2. Redirect URI

Apideck has one callback address for every connector:

https://unify.apideck.com/vault/callback

Add it under Authentication > Web > Redirect URIs if you did not set it during registration. Microsoft matches redirect URIs exactly (see Redirect URI restrictions), so a trailing slash, http instead of https, or any other value will fail the authorisation step. This is the only redirect URI the app needs.

3. Basic information and publisher domain

Open Branding & properties and complete the app's logo, home page URL and terms/privacy links. Two reasons this matters more here than on most connectors:

  • Your customers' administrators see this branding on the Microsoft consent screen when they approve directory access, so it is the moment your app has to look legitimate.
  • Setting a publisher domain is a prerequisite for publisher verification in step 6. The domain cannot be *.onmicrosoft.com; use a DNS-verified custom domain on your tenant.

4. API permissions (Microsoft Graph scopes)

Select API permissions > Add a permission > Microsoft Graph > Delegated permissions, and add:

PermissionWhy the connector needs it
User.Read.AllRead full employee profiles from the directory
User.ReadBasic.AllRead the basic profile set, including direct reports
Group.Read.AllRead groups, which this connector maps to the departments resource

Microsoft's identity platform also uses the standard openid scope (sign-in) and offline_access scope (issuing the refresh token Apideck uses to keep the connection alive). Both are requested as part of the OAuth flow.

Two points worth getting right the first time:

  • Group.Read.All is not optional if you want departments. A connection authorised without it returns 403 on every departments request, while employees and direct reports keep working. Adding the permission later means each connected tenant has to re-consent, because Microsoft does not extend grants that were already issued.
  • All three are read permissions, and that is the full picture. This connector reads employees, direct reports and departments; it creates and updates nothing. There is no reason to request User.ReadWrite.All or any other write scope, and asking for one only makes the consent screen harder for a customer's administrator to approve.

These are administrator-consent permissions by Microsoft's default policy (Graph permissions reference), so plan the connect flow around an administrator in the customer's tenant. Step 7 covers that handoff.

5. Client ID and client secret

Client ID: on the app's Overview page, copy the Application (client) ID. That is the value Apideck calls the Client ID.

Client secret: go to Certificates & secrets > Client secrets > New client secret, add a description and choose an expiry. See Add and manage application credentials for the current screens.

Then the single most common mistake on this connector:

Copy the secret's Value, not its Secret ID. The Value is shown only once, on the page where you created the secret, and cannot be retrieved after you navigate away. The Secret ID sitting next to it is an identifier, not a credential, and pasting it as the Client Secret produces an authorisation failure that looks like a scope or tenant problem.

Microsoft caps client-secret lifetime at 24 months. The secret will expire, and when it does, every connection using this app stops working until you paste a new secret into the Apideck Dashboard. Note the expiry date somewhere you will actually see it, and rotate ahead of time: create the new secret first, update the Dashboard, then delete the old one. A certificate is the longer-lived alternative Microsoft recommends for production apps, but this connector authenticates with a client secret.

6. Publisher verification

If your app is multi-tenant and was registered after 8 November 2020, treat publisher verification as part of shipping it. Because this connector requests permissions beyond basic sign-in, an unverified publisher trips Microsoft's risk-based step-up consent policy: users in other tenants are blocked from consenting, and the consent screen warns that the app comes from an unverified publisher. Verified publishers get a blue verified badge on that same screen instead.

Microsoft charges nothing for publisher verification and it needs no licence. What it does need:

  • A verified Microsoft AI Cloud Partner Program account (formerly Microsoft Partner Network), used as your organisation's partner global account.
  • The app registered in an Entra tenant associated with that partner global account, with a publisher domain set (step 3).
  • The email domain used for partner account verification matching your publisher domain, or a DNS-verified custom domain on the tenant.
  • A user with Application Administrator or Cloud Application Administrator in Entra ID and Partner Admin or Account Admin in Partner Center, signing in with multifactor authentication.

Many Microsoft partners already meet these requirements. Mark your app as publisher verified has the step-by-step. One limitation to know up front: publisher verification is not supported in national clouds, so an app registered in a national cloud tenant cannot be verified.

7. Configure the credentials in Apideck

Open the Apideck Azure Active Directory connector settings in the Apideck Dashboard, switch on Use your own client credentials, and enter:

  • Client ID: the Application (client) ID from step 5.
  • Client Secret: the secret Value from step 5.

Review the scope list so it matches the delegated permissions you granted in step 4, then save. The connector authorises against https://login.microsoftonline.com/common/oauth2/v2.0/authorize and exchanges and refreshes tokens at https://login.microsoftonline.com/common/oauth2/token; Apideck handles the token exchange and refresh for you, and stores the credentials.

That completes your side of the handoff. From here:

  • Each customer's Microsoft administrator grants consent for the directory permissions in their own tenant and authorises the connection in Vault. That happens in their tenant, against your app, and it is the reason steps 3, 4 and 6 are worth doing properly.
  • Access tokens are short-lived (roughly 60 to 90 minutes) and refreshed automatically. A refresh token expires after 90 days of inactivity, so a connection that goes completely unused for three months needs the customer to authorise again.

8. Test the app

Microsoft uses the same app registration for testing and production, so there is no separate set of credentials to swap in. To exercise the app safely, create a free Microsoft Entra tenant through the Microsoft Entra admin centre and populate it with test users and groups. If you would rather test in an existing corporate tenant, point the connection at a dedicated group of test users rather than real staff records.

FAQ and troubleshooting

Three causes, in the order worth checking:

  1. The authorisation targeted the wrong tenant. Confirm the user is signing in with an account in the tenant you intend to connect.
  2. The app is not available to that tenant. Check that Supported account types is set to accounts in any organizational directory (step 1). A single-tenant registration can only ever be consented to in your own tenant.
  3. Administrator consent was never granted. The directory permissions need an administrator's approval in the customer's tenant. See Grant tenant-wide admin consent and share it with the customer's Microsoft administrator, who can pre-approve the app for their whole tenant.

OAuthCodeExchangeError

This means the credentials configured on the connector do not match the app registration in Microsoft Entra ID. Almost always it is the Value/Secret ID mix-up from step 5: re-copy the Application (client) ID as the Client ID and generate a fresh secret, using its Value as the Client Secret. If the secret is more than 24 months old, it has expired regardless of what was pasted, and needs replacing.

Departments requests return 403 while employees work fine

The Group.Read.All permission is missing from the grant. Add it to the app registration (step 4); the affected tenants then need to consent again, because Microsoft does not extend a consent that was already issued.

Complete publisher verification (step 6). Until then, users in tenants other than your own can be blocked from consenting, and administrators who do consent see the warning.

Some directory fields come back empty

Microsoft Entra ID is a directory, not an HR system. Field coverage depends on what each organisation actually maintains in its user profiles, and HR-specific data such as compensation or employment history is not stored there at all. This is a property of the source system rather than something the app registration can change.

More information