Microsoft Entra ID

Connection

Setup

Grant the permissions

Add the Microsoft Graph application permissions under Permissions and grant admin consent for the tenant.

Add Exchange access

Only needed to manage address list visibility. Give the app the Exchange.ManageAsApp role and a certificate to sign in to Exchange Online 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. 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 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.

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.

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.

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.

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.

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"]
  }
}

Basics

Connectors

Administration

Microsoft Entra ID

Microsoft Entra ID

Connection

Setup

Settings

Permissions

microsoft_entra.user

Fields

Default Account Matching Rules

Examples

Employee lifecycle

Engineering access

Contractor access

Leaver offboarding

Oracle HCM worker provisioning

​Microsoft Entra ID

​Connection

​Setup

​Settings

​Permissions

​microsoft_entra.user

​Fields

​Default Account Matching Rules

​Examples

​Employee lifecycle

​Engineering access

​Contractor access

​Leaver offboarding

​Oracle HCM worker provisioning

Microsoft Entra ID

Connection

Setup

Settings

Permissions

microsoft_entra.user

Fields

Default Account Matching Rules

Examples

Employee lifecycle

Engineering access

Contractor access

Leaver offboarding

Oracle HCM worker provisioning