Setup guide

Enumerates all Conditional Access policies, policy templates, named locations and authentication strength policies so the skill can snapshot the tenant before making changes and detect overlapping policies.

↳ Policy.Read.ConditionalAccess covers reading Conditional Access policies and running What If, but not named locations, templates or authentication strength policies. Use it if the skill is being run in audit-only mode.

Creates policies in report-only state, patches state and displayName during promotion or rollback, and deletes a policy that fails the break-glass What If gate.

↳ Omit entirely for read-only auditing runs. There is no narrower write scope for Conditional Access; when a human operator is present, prefer delegated access via the Conditional Access Administrator role instead of an app-only secret.

Reads auditLogs/signIns to measure the real-world impact of a report-only policy, and auditLogs/directoryAudits to confirm the policy change was recorded under the expected actor.

↳ No narrower scope exists for sign-in logs. Note that appliedConditionalAccessPolicies is returned only to callers that also hold a Conditional Access read permission.

Reads the break-glass exclusion group and its membership so the preflight can assert the group exists, has at least two members, and that all members are enabled.

↳ GroupMember.Read.All is sufficient if the skill only needs membership and not group properties.

Resolves user principal names to object IDs for What If personas and checks accountEnabled on break-glass accounts.

↳ No narrower application scope exists for reading arbitrary users in the directory.

Reads directory role membership to confirm at least one break-glass account actually holds Global Administrator, and to resolve role template IDs used in policy include/exclude conditions.

↳ RoleManagement.Read.All is broader and covers other RBAC providers; prefer the Directory-scoped variant.

Resolves the application GUIDs used in includeApplications and excludeApplications to human-readable names so the impact report is legible.

↳ Optional. Skip it and report raw application GUIDs if the operator will not grant it.

Cause: The application permission was added to the app registration but admin consent was never granted, or the wrong permission type (Delegated instead of Application) was selected.

Fix: Entra admin center > Entra ID > App registrations > your app > API permissions. Confirm each row's Type column reads 'Application', then select 'Grant admin consent for <tenant>'. Acquire a fresh token afterwards - existing tokens do not pick up new consent.

Cause: The Secret ID GUID was copied instead of the secret Value, or the secret has expired.

Fix: Create a new client secret under Certificates & secrets > Client secrets and copy the Value column immediately. Update AZURE_CLIENT_SECRET.

Cause: AZURE_CLIENT_ID and AZURE_TENANT_ID belong to different tenants, or the app was registered in a personal directory rather than the target tenant.

Fix: Re-copy both values from the same app's Overview blade in the target tenant. If the app is multi-tenant, provision its service principal in the target tenant first.

Cause: A delegated flow was used against an app whose permissions are configured for app-only, or consent was granted for a different set of scopes than requested.

Fix: For app-only use, request scope=https://graph.microsoft.com/.default with grant_type=client_credentials, and grant admin consent on the API permissions blade. Do not request individual scope strings in the client credentials flow.

Cause: A Conditional Access policy targeting workload identities, or a location/device policy, is blocking the token request for this app or the signed-in administrator.

Fix: Exclude the app's service principal from the workload identity policy, or sign in from a permitted location and device. Use a break-glass account to make the change if the administrator is also blocked.

Cause: GET /auditLogs/signIns requires a Microsoft Entra ID P1 or P2 license on the tenant. The Graph permission alone is not enough.

Fix: Assign a premium license to the tenant. Until then, skip the report-only impact measurement step and rely on What If evaluation only - and say so explicitly in the report.

Cause: The reportOnly* members of appliedConditionalAccessPolicyResult are part of an evolvable enumeration and are hidden unless the caller opts in.

Fix: Add the request header Prefer: include-unknown-enum-members to the GET /auditLogs/signIns call.

Cause: The state value was misspelled or cased wrongly. The only legal values are enabled, disabled and enabledForReportingButNotEnforced - 'reportOnly' is the portal label, not the API value.

Fix: Send "state": "enabledForReportingButNotEnforced" exactly. Also strip read-only properties (id, createdDateTime, modifiedDateTime) from PATCH bodies, which trigger the same 400.

Cause: Microsoft Graph throttling, usually from paging the sign-in logs too aggressively during impact measurement.

Fix: Honour the Retry-After header value in seconds, use $top=1000 to reduce page count, and narrow the createdDateTime filter window.

Cause: The app holds Policy.ReadWrite.ConditionalAccess but not Policy.Read.All. The write scope permits creating policies without granting the ability to read the full policy set back.

Fix: Add Policy.Read.All as an application permission and grant admin consent.