> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Microsoft Entra ID

> Connect TruU IDV to Microsoft Entra ID with a read-only app registration you own: the one-click Cloud Shell script or manual setup, the exact Graph permissions, and how to verify the connection.

This page is for the Entra ID administrator connecting TruU IDV to your tenant. When you finish, TruU can look up employees, their groups and their profile photos, with read-only permissions you can revoke at any time.

TruU IDV reads from your tenant. It never writes to it, never holds administrator credentials, and never sees passwords.

## Before you start

* An Entra ID administrator who can create an app registration and grant admin consent to Microsoft Graph application permissions (Global Administrator or Privileged Role Administrator).
* For the one-click script: access to Azure Cloud Shell, or a terminal with the Azure CLI signed in to the tenant.
* An **Owner** or **Admin** seat in TruU IDV.

### Permissions TruU requests

| Permission | Type | Why |
| - | - | - |
| `User.Read.All` | Application | Read user attributes, contact fields and profile photos |
| `Group.Read.All` | Application | List groups for use case rules and look up a person's memberships |
| `Organization.Read.All` | Application | Read your verified domains, to recognize corporate email addresses |

All three need admin consent. TruU requests no write permission of any kind. If you also use Entra ID for [enterprise SSO into the console](https://docs.truu.ai/idv/admin/sign-in.md#enterprise-sso), that is configured separately.

## Set it up

Open **Settings → Directory** and choose **Microsoft Entra ID**. Pick a setup method.

> [tab] One-click script (easiest)
>
> **1. Copy the command**
>
> The console shows a one-line command for Azure Cloud Shell. It fetches the current setup script for your workspace, so you always run the latest version. **Generate new command** issues a fresh one and invalidates the previous command.
>
> **2. Run it in Azure Cloud Shell**
>
> Open [Azure Cloud Shell](https://shell.azure.com) signed in to the right tenant and paste the command. It creates the app registration, adds the three permissions, grants admin consent, and hands the credentials back to TruU. Your account must be able to grant consent; if it can't, the script stops and the console shows "Your account can't finish this setup."
>
> **3. Wait for the connection**
>
> The console continues on its own when the script finishes. Entra can take a minute to propagate a new app registration; if a permission check fails right away, choose **Retry**.

> [tab] Manual setup
>
> **1. Create an app registration**
>
> In the Entra admin center, go to **App registrations → New registration**. Name it (for example "TruU IDV"), single tenant, no redirect URI.
>
> **2. Add the permissions**
>
> Under **API permissions → Add a permission → Microsoft Graph → Application permissions**, add `User.Read.All`, `Group.Read.All` and `Organization.Read.All`, then choose **Grant admin consent**.
>
> **3. Create a client secret**
>
> Under **Certificates & secrets → New client secret**, create a secret and copy its **Value** (shown once).
>
> **4. Enter the values in TruU**
>
> Enter the **Tenant ID**, **Client ID** (the Application (client) ID) and **Client secret**, then choose **Connect directory**.

### Review the attribute mapping

After connecting, the wizard scans your directory and proposes which attribute each factor uses: Phone (SMS), Email, Knowledge, Badge, Proofing matching and the Face reference photo. Swap in a different attribute where coverage is better, then finish. See [Attribute mapping and coverage](https://docs.truu.ai/idv/connect/directory/overview.md#attribute-mapping-and-coverage).

## Test it

TruU checks the connection when you connect, daily, and on demand from [Credential health](https://docs.truu.ai/idv/admin/credential-health.md): it requests a token with the app's credentials and lists one user, which proves the secret is valid and `User.Read.All` is granted. Verified domains (`Organization.Read.All`) are read during sync and used for [just-in-time provisioning](https://docs.truu.ai/idv/admin/sign-in.md#just-in-time-provisioning).

Then send yourself a verification and confirm your own record is found.

## How it works

* **Live lookups.** Group membership is read for the person at verification time. The group list shown in use case rules is cached briefly and refreshed on sync.
* **Hosts.** TruU calls only `login.microsoftonline.com` and `graph.microsoft.com` for this connection. Nothing needs to be opened on your side.
* **Secrets.** The client secret is held in a managed secrets service and never returned. Rotating it deletes the old value. Every connection change is recorded in the [audit trail](https://docs.truu.ai/idv/security/audit-events.md).

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Checks fail right after the script | The app registration hasn't propagated | Wait a minute and choose **Retry** |
| "Your account can't finish this setup" | Your account can't grant admin consent | Have a Global Administrator or Privileged Role Administrator run the script, or use **Manual setup** |
| Just-in-time provisioning isn't available | `Organization.Read.All` wasn't consented, so no verified domain was read | Grant consent and run **Sync now** |
| SMS fails for some people | Phone numbers aren't in E.164 format | See [SMS](https://docs.truu.ai/idv/factors/sms.md) |
| The secret expired | Entra secrets expire (the script creates one valid for two years) | Credential health flags the failure. Disconnect and reconnect the directory with a new secret; factor settings are kept. |
| Discovery takes a while | Very large tenant | Keep configuring; coverage fills in when the scan finishes |

## Related

* [Connect your directory](https://docs.truu.ai/idv/connect/directory/overview.md)
* [Windows TAP](https://docs.truu.ai/idv/connect/windows-tap.md): needs a separate Entra app registration
* [Microsoft Teams](https://docs.truu.ai/idv/connect/microsoft-teams.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.