Setup guide

Lets the bootstrap identity create the application object, PATCH requiredResourceAccess and keyCredentials, and call addPassword/addKey.

↳ Use AppRegistration.Create if the skill only ever creates new apps, or Application.ReadWrite.OwnedBy to restrict writes to apps this identity owns.

Required to POST appRoleAssignedTo, which is how admin consent for Microsoft Graph application permissions is actually granted.

↳ No narrower Graph permission exists; this is inherently high privilege because it can escalate any principal, so scope it to a dedicated bootstrap app and audit its use.

Required to POST or PATCH oauth2PermissionGrants, which grants delegated Graph permissions tenant-wide with consentType AllPrincipals.

↳ Directory.ReadWrite.All also works but is far broader; prefer this narrower permission.

Reads the Microsoft Graph service principal to translate permission names such as User.Read.All into the appRole and oauth2PermissionScope GUIDs the grant APIs demand.

Example target permission provisioned onto the new app, and the permission used by the verification call GET /v1.0/users?$top=1.

↳ Use User.ReadBasic.All when only id, displayName, mail and userPrincipalName are needed.

Baseline delegated scope proving an interactive flow works; GET /v1.0/me returns the signed-in user without any admin consent.

Entra directory role held by the human operator; least privileged built-in role Microsoft supports for consenting to Microsoft Graph application permissions.

↳ Cloud Application Administrator suffices for consenting to non-Graph APIs and for all other app management, so use it where Graph app roles are not involved.

Entra directory role that lets the human operator create app registrations even when the tenant restricts default member permissions.

Cause: The permission is declared in requiredResourceAccess but nobody has consented. Declaring is not granting.

Fix: Have an admin select 'Grant admin consent for <tenant>' on the API permissions blade, run az ad app permission admin-consent --id <appId>, or POST the appRoleAssignedTo / oauth2PermissionGrants record yourself.

Cause: The Secret ID (a GUID) was copied instead of the Value column, or the secret was truncated or URL-encoded incorrectly.

Fix: Create a new client secret and copy the Value immediately. If it contains characters like '+' or '/', send it with --data-urlencode rather than -d.

Cause: The client secret passed its endDateTime. Entra sends no runtime warning and the failure is total.

Fix: POST /applications/{id}/addPassword to mint a replacement, deploy it, then POST /applications/{id}/removePassword for the old keyId. Move to a certificate to make this rarer.

Cause: The object ID was sent instead of the appId, the app lives in a different tenant, or no service principal was ever created in this tenant.

Fix: Use the Application (client) ID from the Overview blade, confirm AZURE_TENANT_ID matches, and POST /servicePrincipals with {"appId": "<appId>"} if the enterprise application is missing.

Cause: The calling identity lacks the Graph permission or the Entra directory role for the write. Granting Microsoft Graph app roles in particular needs Privileged Role Administrator.

Fix: Add the missing permission to the bootstrap app and consent to it, or assign the human operator Cloud Application Administrator plus Privileged Role Administrator. Do not retry the call unchanged.

Cause: The scope names a resource that has no service principal in this tenant, or the scope string is misspelled - for example 'https://graph.microsoft.com' without the required '/.default'.

Fix: Use scope=https://graph.microsoft.com/.default for client credentials, and create the resource service principal in the tenant if it is genuinely absent.

Cause: A token minted for a different resource (commonly https://management.azure.com/.default) was sent to Microsoft Graph.

Fix: Request a fresh token with scope=https://graph.microsoft.com/.default. One token cannot address two resources.

Cause: Delegated flow only: the redirect URI is missing, registered under the wrong platform type, or differs by scheme, trailing slash or case.

Fix: On Authentication > Platform configurations add the exact URI under the correct platform (Web, SPA or Mobile and desktop). SPAs must use the SPA platform or token redemption fails with AADSTS9002326.

Cause: The client assertion was signed by a key whose certificate is not registered on the app, or the x5t#S256 header does not match the signing certificate.

Fix: Confirm the uploaded certificate's SHA-256 thumbprint equals the base64url x5t#S256 header value, sign with PS256, and set aud to https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token.

Cause: AZURE_TENANT_ID holds a display name, an email domain that is not a verified domain, or a value from a different national cloud.

Fix: Use the Directory (tenant) ID GUID from the Overview blade, or a verified domain, and set AZURE_AUTHORITY_HOST when the tenant is in a US Gov or 21Vianet cloud.