Manage app consent policies
An app consent policy consists of one or more "include" condition sets and zero or more "exclude" condition sets. For an event to be considered in an app consent policy, it must match at least one "include" condition set, and must not match any "exclude" condition set.
Each condition set consists of several conditions. For an event to match a condition set, all conditions in the condition set must be met.
App consent policies where the ID begins with "microsoft-" are built-in policies. Some of these built-in policies are used in existing built-in directory roles. For example, the
microsoft-application-admin app consent policy describes the conditions under which the Application Administrator and Cloud Application Administrator roles are allowed to grant tenant-wide admin consent. Built-in policies can be used in custom directory roles and to configure user consent settings, but cannot be edited or deleted.
A user or service with one of the following:
- Global Administrator directory role
- Privileged Role Administrator directory role
- A custom directory role with the necessary permissions to manage app consent policies
- The Microsoft Graph app role (application permission) Policy.ReadWrite.PermissionGrant (when connecting as an app or a service)
Connect to Microsoft Graph PowerShell.
Connect-MgGraph -Scopes "Policy.ReadWrite.PermissionGrant"
List existing app consent policies
It's a good idea to start by getting familiar with the existing app consent policies in your organization:
List all app consent policies:
Get-MgPolicyPermissionGrantPolicy | ft Id, DisplayName, Description
View the "include" condition sets of a policy:
Get-MgPolicyPermissionGrantPolicyInclude -PermissionGrantPolicyId "microsoft-application-admin" | fl
View the "exclude" condition sets:
Get-MgPolicyPermissionGrantPolicyExclude -PermissionGrantPolicyId "microsoft-application-admin" | fl
Create a custom app consent policy
Follow these steps to create a custom app consent policy:
Create a new empty app consent policy.
New-MgPolicyPermissionGrantPolicy ` -Id "my-custom-policy" ` -DisplayName "My first custom consent policy" ` -Description "This is a sample custom app consent policy."
Add "include" condition sets.
# Include delegated permissions classified "low", for apps from verified publishers New-MgPolicyPermissionGrantPolicyInclude ` -PermissionGrantPolicyId "my-custom-policy" ` -PermissionType "delegated" ` -PermissionClassification "low" ` -ClientApplicationsFromVerifiedPublisherOnly
Repeat this step to add additional "include" condition sets.
Optionally, add "exclude" condition sets.
# Retrieve the service principal for the Azure Management API $azureApi = Get-MgServicePrincipal -Filter "servicePrincipalNames/any(n:n eq 'https://management.azure.com/')" # Exclude delegated permissions for the Azure Management API New-MgPolicyPermissionGrantPolicyExclude ` -PermissionGrantPolicyId "my-custom-policy" ` -PermissionType "delegated" ` -ResourceApplication $azureApi.AppId
Repeat this step to add additional "exclude" condition sets.
Once the app consent policy has been created, you can allow user consent subject to this policy.
Delete a custom app consent policy
The following shows how you can delete a custom app consent policy. This action cannot be undone.
Remove-MgPolicyPermissionGrantPolicy -PermissionGrantPolicyId "my-custom-policy"
Deleted app consent policies cannot be restored. If you accidentally delete a custom app consent policy, you will need to re-create the policy.
The following table provides the list of supported conditions for app consent policies.
|PermissionClassification||The permission classification for the permission being granted, or "all" to match with any permission classification (including permissions which are not classified). Default is "all".|
|PermissionType||The permission type of the permission being granted. Use "application" for application permissions (e.g. app roles) or "delegated" for delegated permissions.
Note: The value "delegatedUserConsentable" indicates delegated permissions which have not been configured by the API publisher to require admin consent—this value may be used in built-in permission grant policies, but cannot be used in custom permission grant policies. Required.
|ResourceApplication||The AppId of the resource application (e.g. the API) for which a permission is being granted, or "any" to match with any resource application or API. Default is "any".|
|Permissions||The list of permission IDs for the specific permissions to match with, or a list with the single value "all" to match with any permission. Default is the single value "all".
|ClientApplicationIds||A list of AppId values for the client applications to match with, or a list with the single value "all" to match any client application. Default is the single value "all".|
|ClientApplicationTenantIds||A list of Azure Active Directory tenant IDs in which the client application is registered, or a list with the single value "all" to match with client apps registered in any tenant. Default is the single value "all".|
|ClientApplicationPublisherIds||A list of Microsoft Partner Network (MPN) IDs for verified publishers of the client application, or a list with the single value "all" to match with client apps from any publisher. Default is the single value "all".|
|ClientApplicationsFromVerifiedPublisherOnly||Set this switch to only match on client applications with a verified publishers. Disable this switch (
To learn more:
- Manage app consent policies using Microsoft Graph
- Configure user consent settings
- Configure the admin consent workflow
- Learn how to manage consent to applications and evaluate consent requests
- Grant tenant-wide admin consent to an application
- Permissions and consent in the Microsoft identity platform
To get help or find answers to your questions: