> ## 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 your directory

> TruU IDV reads your employee directory (Microsoft Entra ID or Okta) live, with read-only access. Choosing a provider, what TruU reads, attribute mapping and coverage, sync, health and disconnecting.

This page is for the administrator connecting TruU IDV to the company directory and keeping it healthy. When you finish you will know what TruU reads, how attribute mapping decides which factors work for whom, and what to watch after go-live.

## Choose your directory

Each workspace connects to one directory. Open **Settings → Directory** and pick a provider:

| Provider | How it connects | Setup |
| - | - | - |
| **Microsoft Entra ID** | An app registration in your tenant with read-only Microsoft Graph permissions | [Connect Microsoft Entra ID](https://docs.truu.ai/idv/connect/directory/entra-id.md) |
| **Okta** | An Okta API Services app with read-only scopes | [Connect Okta](https://docs.truu.ai/idv/connect/directory/okta.md) |

To run separate directories (for example two subsidiaries), use separate workspaces; one account can belong to several. See [Workspaces](https://docs.truu.ai/idv/admin/sign-in.md#workspaces). If you set up TruU IDV from TruU Passwordless, the Entra ID directory can be shared from Passwordless instead; see [TruU Passwordless](https://docs.truu.ai/idv/connect/passwordless.md).

![Directory settings with Microsoft Entra ID and Okta available to connect](https://mintcdn.com/truu-2/ggexkQvmOZdl3yHs/images/idv/settings-directory-light.png?fit=max\&auto=format\&n=ggexkQvmOZdl3yHs\&q=85\&s=739b005f6681d0b432657acfaed8c5f4)

## Live lookup, no mirror

TruU IDV doesn't keep a copy of your directory. At verification time it reads the specific person and their group memberships and uses the answer in the moment.

* **No staleness.** A terminated employee or an old phone number is never served from a cache.
* **Less exposure.** TruU stores connection details, attribute coverage statistics, your attribute mappings and a list of group names and IDs for the use case rule picker. Not employee records.
* **Read-only and revocable.** TruU never writes to your directory. Delete the app in your directory and access ends within about an hour, when TruU's cached token expires.

## What TruU reads

| Used for | What TruU reads |
| - | - |
| Finding people | Users and the attributes you map |
| Use case rules | Group memberships, looked up live at verification time |
| One-time codes | Email and phone attributes, as delivery targets |
| Knowledge and Badge | The challenge and badge identifier attributes you map |
| Face | The profile photo, when Face uses the directory as a photo source (Entra ID only) |

## Attribute mapping and coverage

After connecting, TruU scans which attributes exist and how many people have a value (**coverage**), then proposes which attribute each factor should use. Review the proposal in the connect wizard; you can change it later on each factor's settings.

| Factor needs | Typical Entra ID attributes |
| - | - |
| Phone (SMS) | `mobilePhone`, authentication phone methods, `businessPhones` |
| Email | `mail`, `userPrincipalName`, `otherMails` |
| Employee identifier (Knowledge, Badge) | `employeeId`, `onPremisesSamAccountName`, `extensionAttribute1` |
| Knowledge challenges | `department`, `jobTitle`, `companyName`, `officeLocation` |
| Photo (Face) | The profile photo (`thumbnailPhoto`) |

Each factor takes an ordered list of attributes, and the first one with a value for the person is used.

> [!WARNING]
>
> Coverage is the number that matters. A phone attribute populated for 60% of people makes SMS impossible for the other 40%. Pick a better-covered attribute, add a fallback attribute, or make sure every flow using the factor has a column that needs no directory data, such as Proofing.

Common data problems:

* **Phone numbers rarely use E.164.** `555-123-4567` counts as populated but can't receive a text. See [SMS](https://docs.truu.ai/idv/factors/sms.md).
* **`department` is often empty or inconsistent.** If your organization keeps HR data in extension attributes, map those.
* **Directory photos are old or tiny** (`thumbnailPhoto` is often about 96 pixels). Put the proofing photo first for Face. See [Face](https://docs.truu.ai/idv/factors/face.md).
* **Identifiers must be stable and unique.** For Knowledge and Badge, avoid values that change or repeat across people.

## Sync and health

Lookups are live, so only statistics and catalogs are refreshed:

| Refreshed | When |
| - | - |
| Attribute coverage | Once a day with **Automatic sync** on, and whenever you choose **Sync now** |
| Group list for use case rules | Same, and cached briefly between reads |
| Credential checks | Daily, and on demand from [Credential health](https://docs.truu.ai/idv/admin/credential-health.md) |

Choose **Sync now** after a bulk directory change (phone numbers backfilled, a photo import) so coverage reflects it before you rely on a factor that depends on it.

The page shows the connection status (**Connected**, **Credential issue**, **Expiring soon** or **Error**). If the connection fails, every factor that reads directory data fails, so treat it as an incident. [Credential health](https://docs.truu.ai/idv/admin/credential-health.md) checks it daily.

## Disconnecting

**Disconnect directory** stops factors reading from the directory and switches the console back to sample data. Factor settings are kept; group targeting in use case rules is cleared. To switch providers, disconnect first. You can also revoke access from your side at any time by deleting the app in your directory; it takes effect within about an hour.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| A factor isn't offered to some people | The attribute behind it is empty for them | Check coverage; add a fallback attribute or fix the data |
| A use case rule no longer matches anyone | The group was renamed or deleted in the directory | Choose **Sync now** and re-select the group |
| Coverage looks out of date | No sync since a bulk change | Choose **Sync now** |

## Related

* [Connect Microsoft Entra ID](https://docs.truu.ai/idv/connect/directory/entra-id.md)
* [Connect Okta](https://docs.truu.ai/idv/connect/directory/okta.md)
* [How factors work](https://docs.truu.ai/idv/factors/overview.md)


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