Merge pull request #225168 from omondiatieno/consent-policy-update

manage app consent policies with Microsoft Graph

Author: v-dirichards

articles/active-directory/manage-apps/manage-app-consent-policies.md

@@ -8,10 +8,11 @@ ms.service: active-directory
 ms.subservice: app-mgmt
 ms.workload: identity
 ms.topic: how-to
-ms.date: 09/02/2021
+ms.date: 01/26/2023
 ms.author: jomondi
 ms.reviewer: phsignor, yuhko
 ms.custom: contperf-fy21q2
+zone_pivot_groups: enterprise-apps-minus-portal-aad
 
 #customer intent: As an admin, I want to manage app consent policies for enterprise applications in Azure AD
 ---
@@ -24,16 +25,18 @@ An app consent policy consists of one or more "include" condition sets and zero
 
 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.
+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 can't be edited or deleted.
 
 ## Pre-requisites
 
-1. A user or service with one of the following:
+1. A user or service with one of the following roles:
    - Global Administrator directory role
    - Privileged Role Administrator directory role
    - A custom directory role with the necessary [permissions to manage app consent policies](../roles/custom-consent-permissions.md#managing-app-consent-policies)
    - The Microsoft Graph app role (application permission) Policy.ReadWrite.PermissionGrant (when connecting as an app or a service)
-   
+ 
+:::zone pivot="ms-powershell"
+ 
 1. Connect to [Microsoft Graph PowerShell](/powershell/microsoftgraph/get-started?view=graph-powershell-1.0&preserve-view=true).
 
    ```powershell
@@ -86,7 +89,7 @@ Follow these steps to create a custom app consent policy:
        -ClientApplicationsFromVerifiedPublisherOnly
    ```
 
-   Repeat this step to add additional "include" condition sets.
+   Repeat this step to add more "include" condition sets.
 
 1. Optionally, add "exclude" condition sets.
 
@@ -101,7 +104,7 @@ Follow these steps to create a custom app consent policy:
        -ResourceApplication $azureApi.AppId
    ```
 
-   Repeat this step to add additional "exclude" condition sets.
+   Repeat this step to add more "exclude" condition sets.
 
 Once the app consent policy has been created, you can [allow user consent](configure-user-consent.md?tabs=azure-powershell#allow-user-consent-subject-to-an-app-consent-policy) subject to this policy.
 
@@ -113,26 +116,113 @@ Once the app consent policy has been created, you can [allow user consent](confi
    Remove-MgPolicyPermissionGrantPolicy -PermissionGrantPolicyId "my-custom-policy"
    ```
 
-> [!WARNING]
-> Deleted app consent policies cannot be restored. If you accidentally delete a custom app consent policy, you will need to re-create the policy.
+:::zone-end
 
----
+:::zone pivot="ms-graph"
+
+To manage app consent policies, sign in to [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) with one of the roles listed in the prerequisite section.
+
+## List existing app consent policies
+
+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:
+
+```http
+GET /policies/permissionGrantPolicies?$select=id,displayName,description
+```
+
+1. View the "include" condition sets of a policy:
+
+```http
+GET /policies/permissionGrantPolicies/{ microsoft-application-admin }/includes
+```
+
+1. View the "exclude" condition sets:
+
+```http
+GET /policies/permissionGrantPolicies/{ microsoft-application-admin }/excludes
+```
+
+## Create a custom app consent policy
+
+Follow these steps to create a custom app consent policy:
+
+1. Create a new empty app consent policy.
 
+```http
+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
+
+```http
+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.
+
+1. Optionally, add "exclude" condition sets.
+     Exclude delegated permissions for the Azure Management API (appId 46e6adf4-a9cf-4b60-9390-0ba6fb00bf6b)
+```http
+POST https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies/my-custom-policy /excludes
+Content-Type: application/json
+
+{
+  "permissionType": "delegated",
+  "resourceApplication": "46e6adf4-a9cf-4b60-9390-0ba6fb00bf6b "
+}
+```
+
+   Repeat this step to add more "exclude" condition sets.
+
+Once the app consent policy has been created, you can [allow user consent](configure-user-consent.md?tabs=azure-powershell#allow-user-consent-subject-to-an-app-consent-policy) subject to this policy.
+
+## Delete a custom app consent policy
+
+1. The following shows how you can delete a custom app consent policy. **This action can’t be undone.**
+
+```http
+DELETE https://graph.microsoft.com/v1.0/policies/permissionGrantPolicies/ my-custom-policy
+```
+
+:::zone-end
+
+> [!WARNING]
+> Deleted app consent policies cannot be restored. If you accidentally delete a custom app consent policy, you will need to re-create the policy.
 ### Supported conditions
 
 The following table provides the list of supported conditions for app consent policies.
 
 | Condition | Description|
 |:---------------|:----------|
-| PermissionClassification | The [permission classification](configure-permission-classifications.md) 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. <br><br>**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". |
+| PermissionClassification | The [permission classification](configure-permission-classifications.md) for the permission being granted, or "all" to match with any permission classification (including permissions that aren't classified). Default is "all". |
+| PermissionType | The permission type of the permission being granted. Use "application" for application permissions (for example, app roles) or "delegated" for delegated permissions. <br><br>**Note**: The value "delegatedUserConsentable" indicates delegated permissions that haven't been configured by the API publisher to require admin consent. This value may be used in built-in permission grant policies, but can't be used in custom permission grant policies. Required. |
+| ResourceApplication | The **AppId** of the resource application (for example, 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". <ul><li>Delegated permission IDs can be found in the **OAuth2Permissions** property of the API's ServicePrincipal object.</li><li>Application permission IDs can be found in the **AppRoles** property of the API's ServicePrincipal object.</li></ol> |
 | 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](../develop/publisher-verification-overview.md) 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](../develop/publisher-verification-overview.md). Disable this switch (`-ClientApplicationsFromVerifiedPublisherOnly:$false`) to match on any client app, even if it does not have a verified publisher. Default is `$false`. |
+| ClientApplicationsFromVerifiedPublisherOnly | Set this switch to only match on client applications with a [verified publishers](../develop/publisher-verification-overview.md). Disable this switch (`-ClientApplicationsFromVerifiedPublisherOnly:$false`) to match on any client app, even if it doesn't have a verified publisher. Default is `$false`. |
 
+> [!WARNING]
+> Deleted app consent policies cannot be restored. If you accidentally delete a custom app consent policy, you will need to re-create the policy.
 ## Next steps
 
 To learn more:

articles/zone-pivot-groups.yml

@@ -1847,6 +1847,15 @@ groups:
     title: Microsoft Graph PowerShell
   - id: ms-graph
     title: Microsoft Graph
+## Template without portal and Azure AD Graph
+- id: enterprise-apps-minus-portal-aad
+  title: Manage Enterprise apps
+  prompt: Choose an option
+  pivots:
+  - id: ms-powershell
+    title: Microsoft Graph PowerShell
+  - id: ms-graph
+    title: Microsoft Graph
 ## template without graph
 - id: enterprise-apps-minus-graph
   title: Manage Enterprise apps