> ## Documentation Index
> Fetch the complete documentation index at: https://klef.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Entra ID
Microsoft Entra ID
## Connection
### Setup
[Register an app](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app) for
Klef in your tenant, then [add a client secret](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret#add-a-credential-to-your-application) to it.
Add the Microsoft Graph application permissions under [Permissions](#permissions) and
[grant admin consent](https://learn.microsoft.com/entra/identity/enterprise-apps/grant-admin-consent)
for the tenant.
Only needed to manage address list visibility. Give the app the `Exchange.ManageAsApp` role and a
certificate to [sign in to Exchange Online](https://learn.microsoft.com/powershell/exchange/app-only-auth-powershell-v2)
with.
### Settings
| Setting | Required | Description |
| ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Tenant ID | Yes | Directory (tenant) ID of your Entra tenant. |
| Client ID | Yes | Application (client) ID of the app registration Klef signs in as. |
| Client secret | Yes | Client secret of that app registration. Stored encrypted. |
| Exchange organization | | Exchange Online organization, such as contoso.onmicrosoft.com. Needed to manage address list visibility. |
| Exchange certificate (base64 PFX) | | Certificate the app registration uses for Exchange Online, as a base64 PFX with its private key. Stored encrypted. |
| Exchange certificate password | | Password of that certificate. Stored encrypted. |
| First sign-in | | How credentials are handled. Choose a Temporary Access Pass when the tenant only lets people register MFA from a trusted location or device. |
| Temporary Access Pass lifetime (minutes) | | How long a pass works (from 10 minutes to 30 days, 480 by default). |
| Temporary Access Pass usable once | | Whether a pass works for one sign-in only. |
### Permissions
Minimum permissions the connection requires.
| Capability | Required | Granted by (any one) |
| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| Read and write users | Yes | `User.ReadWrite.All`, `Directory.ReadWrite.All` |
| Enable and disable accounts | Yes | `User.EnableDisableAccount.All`, `User.ReadWrite.All`, `Directory.ReadWrite.All` |
| Update phone numbers | | `User-Phone.ReadWrite.All`, `User.ReadWrite.All`, `Directory.ReadWrite.All` |
| Manage group membership | Yes | `GroupMember.ReadWrite.All`, `Group.ReadWrite.All`, `Directory.ReadWrite.All` |
| Read licensing (subscribed SKUs) | Yes | `Organization.Read.All`, `Directory.Read.All`, `Directory.ReadWrite.All`, `LicenseAssignment.Read.All` |
| Reset passwords | Yes | `User-PasswordProfile.ReadWrite.All` |
| Read domains (federated-domain check) | | `Domain.Read.All`, `Directory.Read.All`, `Directory.ReadWrite.All` |
| Issue Temporary Access Passes | | `UserAuthenticationMethod.ReadWrite.All` |
| Read the authentication methods policy | | `Policy.Read.All`, `Policy.ReadWrite.AuthenticationMethod` |
| Sign in to Exchange Online (address list visibility) | | `Exchange.ManageAsApp` |
## microsoft\_entra.user
### Fields
| Field | Type | Required | Description |
| ------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `displayName` | string, up to 256 | Yes | Name shown in the directory and address lists. |
| `mailNickname` | string, up to 64 | Yes | Mail alias, without the domain. |
| `userPrincipalName` | string, up to 113 | Yes | Sign-in name, such as [ada@example.com](mailto:ada@example.com). The domain must be verified in the tenant. |
| `accountEnabled` | bool | Yes | Whether the user can sign in. |
| `showInAddressList` | bool | | Whether the mailbox appears in the global address list. Offered only when the connection has Exchange settings. |
| `givenName` | string | | First name. |
| `surname` | string | | Last name. |
| `jobTitle` | string | | Job title. |
| `department` | string | | Department name. |
| `employeeId` | string | | Employee number, usually from the HR system. |
| `usageLocation` | string, up to 2 | | Two-letter country code, such as US. Required before a license can be assigned. |
| `mail` (Email) | string | | Primary email address. |
| `companyName` | string, up to 64 | | Company name. |
| `employeeType` | string, up to 64 | | Kind of worker, such as Employee or Contractor. |
| `preferredLanguage` | string | | Language code, such as en-US. |
| `officeLocation` | string, up to 128 | | Office or building. |
| `streetAddress` | string | | Street address. |
| `city` | string, up to 128 | | City. |
| `state` | string, up to 128 | | State or region. |
| `postalCode` | string, up to 40 | | Postal code. |
| `country` | string, up to 128 | | Country or region. |
| `mobilePhone` | string, up to 64 | | Mobile phone number. |
| `businessPhone` | string, up to 64 | | Office phone number. |
| `manager` | link | | The user's manager, set from the worker's manager. |
| `groups` | grant | | Groups the user is a direct member of. Dynamic groups are not offered. One row grants one group. |
| `groups[]` (Group) | string | | Group ID. |
| `licenses` | grant | | Licenses assigned directly to the user. One row grants one license. |
| `licenses[]` | string | | License SKU, such as SPE\_E3. |
### Default Account Matching Rules
When Klef [adopts](/docs/adoption) an account that already exists in Microsoft Entra ID, it works out whose it is by trying these in order. A connection can override them.
| Account field | Worker field |
| ------------- | ----------------------- |
| `mail` | `worker.business_email` |
| `employeeId` | `worker.employee_id` |
## Examples
### Employee lifecycle
Stage a Microsoft account before day one, switch on Microsoft 365 and Slack when they start, and shut both down when they leave.
```hcl theme={null}
stage active {
target microsoft_entra.user {
userPrincipalName = worker.business_email
mailNickname = worker.employee_id
displayName = worker.display_name
givenName = worker.legal_name.given
surname = worker.legal_name.family
jobTitle = worker.job.name
department = worker.department.name
employeeId = worker.employee_id
accountEnabled = true
usageLocation = "US"
licenses = ["SPE_E3"]
groups = ["All Employees"]
}
}
```
### Engineering access
The engineering group, a seat on the GitHub engineering team and the incident channels, with GitHub removed when they leave.
```hcl theme={null}
stage active {
target microsoft_entra.user {
userPrincipalName = worker.business_email
mailNickname = worker.employee_id
displayName = worker.display_name
accountEnabled = true
groups = ["All Employees", "Engineering"]
}
}
```
### Contractor access
Unlicensed Microsoft, Slack and AWS access for contractors that expires on their end date, with a warning to their manager first.
```hcl theme={null}
stage active {
target microsoft_entra.user {
userPrincipalName = worker.business_email
mailNickname = worker.employee_id
displayName = "{{ worker.display_name }} (Contractor)"
jobTitle = worker.job.name
accountEnabled = true
usageLocation = "US"
licenses = []
groups = ["Contractors"]
}
}
```
### Leaver offboarding
Ask the manager to plan the handover, then close Microsoft, Slack and GitHub access on the last day and tell security.
```hcl theme={null}
stage terminated {
target microsoft_entra.user {
userPrincipalName = worker.business_email
mailNickname = worker.employee_id
displayName = worker.display_name
accountEnabled = false
licenses = []
groups = []
}
}
```
### Oracle HCM worker provisioning
An Entra mailbox and a nested Oracle Fusion employment record across five stages, with a worker's assignments expanded one for one.
```hcl theme={null}
stage active {
target microsoft_entra.user {
userPrincipalName = worker.business_email
mailNickname = worker.employee_id
displayName = worker.display_name
accountEnabled = true
givenName = worker.legal_name.given
surname = worker.legal_name.family
jobTitle = worker.job.name
department = worker.department.name
employeeId = worker.employee_id
usageLocation = "US"
licenses = ["SPE_E3"]
groups = ["All Employees"]
}
}
```