Setup guide

Create users, update their attributes, set accountEnabled to false, assign a manager, and soft-delete a leaver.

↳ If you never hard-delete, replace it with User.Create + User.ReadUpdate.All + User.EnableDisableAccount.All + User.Read.All. DELETE /users/{id} has no narrower alternative.

Read user profiles for idempotent lookups, enumerate directReports, and list soft-deleted users before reusing a UPN.

Add and remove users from security and Microsoft 365 groups during joiner, mover and leaver runs.

↳ Use GroupMember.Read.All alone if the deployment is report-only and never writes memberships.

Resolve groups by displayName and read groupTypes, mailEnabled, securityEnabled and isAssignableToRole to decide whether a group is safe to write.

↳ GroupMember.Read.All covers membership reads but not the group metadata this skill branches on, so keep Group.Read.All.

Call POST /users/{id}/assignLicense to add or remove SKUs, and read /subscribedSkus for seat availability.

↳ LicenseAssignment.Read.All is enough if the skill only reports license state and never changes it.

Invalidate refresh tokens during offboarding, because disabling the account alone does not promptly end active sessions.

↳ This is already the narrowest permission for the action; do not substitute User.ReadWrite.All.

Restore a soft-deleted user from /directory/deletedItems when rolling back a mistaken offboarding.

↳ Omit entirely if you never restore; merely listing soft-deleted users only needs User.Read.All.

Preflight the tenant's verifiedDomains before creating a UPN, and act as the app-only smoke test in place of /me.

↳ Directory.Read.All also works but is far broader; prefer Organization.Read.All.

Write employeeHireDate and employeeLeaveDateTime so Entra Lifecycle Workflows can trigger on them.

↳ Optional. Skip it unless you actually stamp lifecycle dates; Microsoft requires it be paired with User.Read.All.

Required only to add or remove members of role-assignable groups (isAssignableToRole = true).

↳ Highly privileged - it can grant directory roles. Do not consent it unless you genuinely manage role-assignable groups; otherwise have the skill stop for human approval on those groups.

Cause: AZURE_CLIENT_SECRET holds the 'Secret ID' GUID from the Client secrets table instead of the 'Value' column, or the secret has expired.

Fix: Create a new client secret and copy the 'Value' column immediately - it is shown only once. If your value looks like a GUID, it is the wrong field.

Cause: AZURE_CLIENT_ID belongs to a different tenant, or the app registration exists but has no service principal in this tenant.

Fix: Re-copy the client ID from the app's Overview blade and confirm AZURE_TENANT_ID names the same directory.

Cause: AZURE_TENANT_ID is malformed - commonly an Azure subscription ID, or a value carrying stray quotes or whitespace from a .env file.

Fix: Use the 'Directory (tenant) ID' GUID or the tenant's onmicrosoft.com domain, unquoted and untrimmed.

Cause: The code requested a delegated scope instead of the app-only scope, or admin consent was never granted.

Fix: Request scope=https://graph.microsoft.com/.default with grant_type=client_credentials, and click 'Grant admin consent' on the API permissions blade.

Cause: Admin consent was never granted, a required permission is missing, or the target user holds a directory role the app is not allowed to act on.

Fix: Confirm every permission row shows 'Granted for <tenant>', then assign the service principal the 'User Administrator' directory role.

Cause: The UPN is taken - frequently by a soft-deleted user that still holds the UPN and proxyAddresses for 30 days.

Fix: Query GET /directory/deletedItems/microsoft.graph.user, then either restore that object or permanently delete it before reusing the UPN.

Cause: POST /groups/{id}/members/$ref was called for a user who is already a member. Graph returns 400 here, not 409.

Fix: Treat this specific 400 as idempotent success instead of retrying or failing the run.

Cause: The user has onPremisesSyncEnabled = true, so Active Directory is the source of authority for that attribute.

Fix: Make the change in on-premises AD and let Entra Connect sync it, or exclude synced users from the run.

Cause: Directory replication lag immediately after creating a user or group, or an objectId from the wrong tenant.

Fix: Retry after a few seconds with backoff before treating it as a hard failure; verify the id belongs to this tenant.

Cause: usageLocation is unset or the SKU is not sold in that country. CountViolation instead means the tenant has no free seats.

Fix: PATCH usageLocation with an ISO 3166-1 alpha-2 code before assigning, and check prepaidUnits.enabled minus consumedUnits on /subscribedSkus.

Cause: Microsoft Graph per-app, per-tenant throttling, typically triggered by bulk joiner or reconcile runs.

Fix: Sleep for exactly the Retry-After value, cap concurrency at 4, and batch with POST /$batch at no more than 20 requests per batch.

Cause: The tenant or the calling principal hit its directory object creation limit.

Fix: Delete unused objects, permanently purge soft-deleted users, or raise a Microsoft support request to increase the tenant quota.