Manage app consent policies - Microsoft Entra ID (original) (raw)

App consent policies are a way to manage the permissions that apps have to access data in your organization. They're used to control what apps users can consent to and to ensure that apps meet certain criteria before they can access data. These policies help organizations maintain control over their data and ensure they only grant access to trusted apps. With Microsoft Graph and Microsoft Graph PowerShell, you can view and manage app consent policies.

In this article, you learn how to manage built-in and custom app consent policies to control when consent can be granted. App consent policies can be assigned to specific users or groups using custom roles, or you can set a default app consent policy for end-users in your organization.

Note

There are other ways to give a user or service principal the ability to grant consent besides using app consent policies. Don't use the list of principals assigned roles with consent policies attached as an exhaustive list of what can grant consent in your organization.

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. The exclusion and inclusions are used to determine whether the actor affected by the given policy can grant consent or not.

There are three main parts of app consent policies:

Supported conditions

Each condition set consists of several conditions. For an event to match a condition set, all conditions in the condition set must be met. For example, a condition set might specify "Client applications that are publisher verified, created in this tenant, and requesting Microsoft Graph delegated Mail.Read" wouldn't match on a consent request for a client application that is publisher verified, created in the tenant, and requesting openid and profile scopes.

Condition sets include one or more properties used to define characteristics of the app or permissions requested. A full list of the properties is located here.

Every tenant comes with a set of app consent policies that are the same across all tenants. 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 or to configure an organization's default consent policy. These policies can't be edited. A list of the built-in policies are:

Warning

Microsoft-user-default-recommended and microsoft-user-default-allow-consent-apps are a Microsoft managed policies. The conditions included in the policies are automatically updated based on Microsoft's latest security recommendations for end-user consent.

The setting labeled "Let Microsoft manage your consent settings," the Microsoft managed policy, will update with Microsoft's latest recommended default consent settings. This is also the default for a new tenant. The setting's rules are currently: End users can consent for any user consentable delegated permissions EXCEPT:

Mail client policy

An additional policy is enabled by default is the microsoft-user-allow-default-consent-apps policy. This policy allows end-users in your organization to consent for popular mail applications for mail permissions. When this policy is enabled, end users will be able to consent for specific delegated mail permissions (Microsoft Graph and Office 365 Exchange Online permissions: EAS.AccessAsUser.All, EWS.AccessAsUser.All, IMAP.AccessAsUser.All, POP.AccessAsUser.All) for the following applications:

A user can have more than one policy that allows them to give consent. Each policy is evaluated separately (as in, an exclusion from one policy does not affect inclusions of another policy) and the user only needs one policy to approve to be allowed to consent for a specific event. For example, an application admin can consent to everything a regular user can (thanks to the default policy applied to all users), and they also have broader permissions through the microsoft-application-admin policy, which lets them approve requests for any API permission—except Microsoft Graph app roles.

Similarly, a user or service principal can be given the ability to grant consent through means other than an app consent policy. For example: a user that is assigned as 'owner' to a service principal can grant consent for the app roles that service principal exposes, even if that user hasn't been assigned any roles with consent policies attached; an application assigned the Application.ReadWrite.All application permission can grant consent for any app role (except those exposed by Microsoft Graph). The user or service principal only needs one authorization mechanism to approve to be allowed to grant consent for a specific event.

Prerequisites

To manage app consent policies for applications with Microsoft Graph PowerShell, connect to Microsoft Graph PowerShell.

Connect-MgGraph -Scopes "Policy.ReadWrite.PermissionGrant"

It's a good idea to start by getting familiar with the existing app consent policies in your organization:

  1. List all app consent policies. This shows all built-in policies and any custom policies your organization created:
Get-MgPolicyPermissionGrantPolicy | ft Id, DisplayName, Description
  1. View the "include" condition sets of a policy:
Get-MgPolicyPermissionGrantPolicyInclude -PermissionGrantPolicyId "microsoft-application-admin" | fl
  1. View the "exclude" condition sets:
Get-MgPolicyPermissionGrantPolicyExclude -PermissionGrantPolicyId "microsoft-application-admin" | fl

Follow these steps to create a custom app consent policy:

  1. 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."
  1. 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 more "include" condition sets. 3. 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 more "exclude" condition sets.

After creating the app consent policy, you need to assign it to a custom role in Microsoft Entra ID. You then need to assign users to that custom role, which is attached to the app consent policy you created. For more information on how to assign the app consent policy to a custom role, see App consent permissions for custom roles.

The following cmdlet shows how you can delete a custom app consent policy.

   Remove-MgPolicyPermissionGrantPolicy -PermissionGrantPolicyId "my-custom-policy"

To manage app consent policies, sign in to Graph Explorer with one of the roles listed in the prerequisite section.

You need to consent to the Policy.ReadWrite.PermissionGrant permission.

It's a good idea to start by getting familiar with the existing app consent policies in your organization:

  1. List all app consent policies. This shows all built-in policies and any custom policies your organization created:
GET /policies/permissionGrantPolicies?$select=id,displayName,description
  1. View the "include" condition sets of a policy:
GET /policies/permissionGrantPolicies/{ microsoft-application-admin }/includes
  1. View the "exclude" condition sets:
GET /policies/permissionGrantPolicies/{ microsoft-application-admin }/excludes

Follow these steps to create a custom app consent policy:

  1. Create a new empty app consent policy.
POST https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies  
Content-Type: application/json  
{  
  "id": "my-custom-policy",  
  "displayName": "My first custom consent policy",  
  "description": "This is a sample custom app consent policy"  
}
  1. Add "include" condition sets.
    Include delegated permissions classified "low" for apps from verified publishers
POST https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies/{ my-custom-policy }/includes  
Content-Type: application/json  
{  
  "permissionType": "delegated",  
  "PermissionClassification": "low",  
  "clientApplicationsFromVerifiedPublisherOnly": true  
}

Repeat this step to add more "include" condition sets. 3. Optionally, add "exclude" condition sets. Exclude delegated permissions for the Azure Management API (appId 00001111-aaaa-2222-bbbb-3333cccc4444) 

POST https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies/my-custom-policy /excludes  
Content-Type: application/json  
{  
  "permissionType": "delegated",  
  "resourceApplication": "00001111-aaaa-2222-bbbb-3333cccc4444 "  
}

Repeat this step to add more "exclude" condition sets.

After creating the app consent policy, you need to assign it to a custom role in Microsoft Entra ID. You then need to assign users to that custom role, which is attached to the app consent policy you created. For more information on how to assign the app consent policy to a custom role, see App consent permissions for custom roles.

  1. The following shows how you can delete a custom app consent policy.
DELETE https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies/ my-custom-policy

Warning

Deleted app consent policies can't be restored. If you accidentally delete a custom app consent policy, you need to re-create the policy.

Next steps

To get help or find answers to your questions: