Entra ID app-registration setup

The entra-id connector authenticates to Microsoft Graph with an app registration using the OAuth2 client-credentials grant. This guide covers creating the app registration, granting the required application permissions, consenting to them, and creating a client secret. See Entra ID connector for the command reference.

1. Create (or reuse) an app registration

1. In the Microsoft Entra admin center go to Identity → Applications → App registrations → New registration.
2. Name it (e.g. Floh Provisioning). Leave "Supported account types" as single tenant. No redirect URI is needed (this is a daemon/service app).
3. After creation, copy:
4. Application (client) ID → connector clientId
5. Directory (tenant) ID → connector tenantId (a GUID; a verified tenant domain such as contoso.onmicrosoft.com also works)

2. Grant application permissions

Under API permissions → Add a permission → Microsoft Graph → Application permissions, add:

Permission	Why
User.ReadWrite.All	create/update/disable/delete users
User-PasswordProfile.ReadWrite.All	setPassword / first-password — app-only passwordProfile updates require this in addition to User.ReadWrite.All
Group.ReadWrite.All	create/update/delete groups, manage membership
Directory.Read.All	connectivity test + tenant-GUID resolution

Then click Grant admin consent for <tenant>. Application permissions do not take effect until an administrator consents — without consent the connector test command returns 403 Authorization_RequestDenied.

Grant only the permissions you need. If a deployment only manages groups, omit the two user permissions (and vice versa); add User-PasswordProfile.ReadWrite.All only if you use setPassword / first-password. Directory.Read.All is needed for the connectivity test and for resolving the tenant GUID when tenantId is a domain.

3. Create a client secret

1. Certificates & secrets → Client secrets → New client secret.
2. Choose an expiry and copy the secret value immediately (it is shown only once) → connector clientSecret.
3. Rotate before expiry; update the connector instance's clientSecret with the new value.

Certificate-based credentials are not supported in v1 — use a client secret.

4. Configure the connector

Create an entra-id connector instance (Connectors UI or API) with the values from the previous steps:

{
  "tenantId": "11111111-2222-3333-4444-555555555555",
  "clientId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "clientSecret": "<client-secret-value>",
  "defaultDomain": "contoso.com"
}

Run the connector test command. Success returns tokenObtained: true with the tenant organizationName.

Troubleshooting

Symptom	Likely cause / fix
test → Microsoft Entra ID error (401): invalid_client …	Wrong/expired clientSecret or wrong clientId. Recreate the secret.
test → Microsoft Entra ID error (403): Authorization_RequestDenied	Admin consent not granted, or a required permission is missing.
createUser → 400 complexity / property error	Password doesn't meet tenant policy, or userPrincipalName domain isn't verified.
setPassword fails for a specific user	The user is federated/synced from on-prem AD; cloud password change isn't allowed.
tenantId must be a directory (tenant) GUID or a tenant domain	common/organizations/consumers are not valid for client-credentials — use the concrete tenant.

Security notes

• clientSecret is stored encrypted at rest (connector secret field) and is never written to logs — outbound requests log only the method and a sanitized URL.
• Connector diagnostics records the HTTP statusCode and Graph error code only; raw Graph response bodies (which can contain PII such as a conflicting UPN) are not persisted.
• All Graph traffic is validated through the shared SSRF-safe HTTP client.