Update user consent settings for new options and new UX

Author: luleonpla

articles/active-directory/manage-apps/configure-user-consent.md

@@ -9,64 +9,199 @@ ms.service: active-directory
 ms.subservice: app-mgmt
 ms.workload: identity
 ms.topic: conceptual
-ms.date: 10/22/2018
+ms.date: 05/19/2020
 ms.author: mimart
 ms.reviewer: arvindh
 ms.collection: M365-identity-device-management
 ---
 
 # Configure how end-users consent to applications
 
-Applications can integrate with the Microsoft Identity platform to allow users to sign in using their work or school account in Azure Active Directory (Azure AD), and to access your organization's data to deliver rich data-driven experiences. Different permissions allow the application different level of access to your users' and your organization's data.
+Applications can integrate with the Microsoft identity platform, allowing users to sign in with their work or school account and access your organization's data to deliver rich data-driven experiences.
 
-By default, users can consent to applications accessing your organization's data, although only for some permissions. For example, by default a user can consent to allow an app to access their own mailbox or the Teams conversations for a team the user owns, but cannot consent to allow an app unattended access to read and write to all SharePoint sites in your organization. While allowing users to consent by themselves does allow users to easily acquire useful applications that integrate with Microsoft 365, Azure and other services, it can represent a risk if not used and monitored carefully.
+Before an application can access your organization's data, a user must grant the application permissions to access data. Different permissions allow different levels of access.
 
-Microsoft recommends disabling future user consent operations to help reduce your surface area and mitigate this risk. If user consent is disabled, previous consent grants will still be honored but all future consent operations must be performed by an administrator. Tenant-wide admin consent can be requested by users through an integrated [admin consent request workflow](configure-admin-consent-workflow.md) or through your own support processes. See [Five steps to securing your identity infrastructure](../../security/fundamentals/steps-secure-identity.md) for more details.
+By default, all users are allowed to consent to applications for permissions which do not require administrator consent. For example, by default, a user can consent to allow an app to access their mailbox, but cannot consent to allow an app unfettered access to read and write to all files in your organization.
 
-## Configure user consent to applications
-### Disable or enable user consent from the Azure portal
+Allowing users to grant apps access to data allow users to easily acquire useful applications and be productive, but in some situations this configuration can represent a risk if not monitored and controlled carefully.
 
-You can use the Azure portal to disable or enable users' ability to consent to applications accessing your organization's data:
+## User consent settings
+
+You can control in which cases users can consent to applications by choosing the consent policy which will apply to all users. There are three options out of the box:
+
+* **Disable user consent**. With this setting, users cannot grant permissions to applications. Users will be able to continue to sign in to apps they had previously consented to or which are consented to by administrators on their behalf, but they will not be allowed to consent to new permissions, or to new apps on their own. Only users who have been granted a directory role which includes the permission to grant consent will be able to consent.
+
+* **Users can consent to apps from verified publishers, but only for permissions you select (preview)**. With this consent policy, all users can only consent to apps which were published by a [verified publisher](../develop/publisher-verification-overview.md) and apps which are registered in your tenant. Users can only consent to the permissions you have classified as "Low impact".
+
+  > [!IMPORTANT]
+  > Don't forget to [classify permissions](#configure-permission-classifications-preview) to select which permissions users are allowed to consent to.
+
+* **Users can consent to all apps**. With this setting all users can consent to for any apps.
+
+  > [!WARNING]
+  > This option allows all users to consent to any permission which does not require admin consent, for any application. Microsoft recommends allowing user consent only for apps from verified publishers.
+
+To reduce the risk of malicious applications attempting to trick users into granting them access to your organization's data, Microsoft recommends allowing user consent only for applications which have been published by a [verified publisher](../develop/publisher-verification-overview.md).
+
+> [!NOTE]
+> To ensure users have a simple way to request administrator review and approval for an application they are not allowed to consent to, consider enabling the [admin consent request workflow](configure-admin-consent-workflow.md).
+
+### Configure user consent settings from the Azure portal
+
+You can use the Azure portal to configure user consent settings:
 
 1. Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator](../users-groups-roles/directory-assign-admin-roles.md#global-administrator--company-administrator).
-2. Select **Azure Active Directory**, then **Enterprise applications**, then **User settings**.
-3. Enable or disable user consent with the control labeled **Users can consent to apps accessing company data on their behalf**.
-4. (Optional) Configure [admin consent request workflow](configure-admin-consent-workflow.md) to ensure users who aren't allowed to consent to an app can request approval.
+2. Select **Azure Active Directory** > **Enterprise applications** > **Consent and permissions** > **User consent settings**.
+3. Under **User consent for applications** select which consent setting you'd like to configure for all users.
+4. Click **Save** to save your settings.
+
+![User consent settings](./media/configure-user-consent/configure-consent-setting-for-all-users.png)
 
 > [!TIP]
-> To allow users to request an administrator's review of an application that the user is not allowed to consent to (for example, because user consent has been disabled, or because the application is requesting permissions that the user is not allowed to grant), consider [configuring the admin consent workflow](configure-admin-consent-workflow.md).
+> Consider [enabling the admin consent workflow](configure-admin-consent-workflow.md) to allow users to request an administrator's review of an application that the user is not allowed to consent to. For example, because user consent has been disabled, or because the application is requesting permissions that the user is not allowed to grant.
 
-### Disable or enable user consent using PowerShell
+### Configure user consent settings using PowerShell
 
-You can use the Azure AD PowerShell v1 module ([MSOnline](https://docs.microsoft.com/powershell/module/msonline/?view=azureadps-1.0)), to enable or disable users' ability to consent to applications accessing your organization's data.
+You can use the latest version of the [AzureADPreview](https://docs.microsoft.com/powershell/azure/active-directory/install-adv2?view=azureadps-2.0-preview) module to choose which consent policy governs user consent for applications.
 
-1. Sign in to your organization by running this cmdlet:
+* **Disable user consent**. To disable user consent, set the consent policies which govern user consent to be empty:
 
-    ```powershell
-    Connect-MsolService
-    ```
+  ```powershell
+  Set-AzureADMSAuthorizationPolicy `
+     -Id "authorizationPolicy" `
+     -PermissionGrantPolicyIdsAssignedToDefaultUserRole @()
+  ```
 
-2. Check if user consent is enabled by running this cmdlet:
+* **Allow user consent for apps from verified publishers, for selected permissions (preview)**. To allow limited user consent only for apps from verified publishers and apps registered in your tenant, only for permissions you classify as "Low impact", configure the built-in consent policy named `microsoft-user-default-low`:
 
-    ```powershell
-    Get-MsolCompanyInformation | Format-List UsersPermissionToUserConsentToAppEnabled
-    ```
+  ```powershell
+  Set-AzureADMSAuthorizationPolicy `
+     -Id "authorizationPolicy" `
+     -PermissionGrantPolicyIdsAssignedToDefaultUserRole @("microsoft-user-default-low")
+  ```
 
-3. Enable or disable user consent. For example, to disable user consent, run this cmdlet:
+  > [!IMPORTANT]
+  > Don't forget to [classify permissions](#configure-permission-classifications-preview) to select which permissions users are allowed to consent to.
 
-    ```powershell
-    Set-MsolCompanySettings -UsersPermissionToUserConsentToAppEnabled $false
-    ```
+* **Allow user consent for all apps**. To allow user consent for all apps:
 
-## Configure group owner consent to apps accessing group data
+  ```powershell
+  Set-AzureADMSAuthorizationPolicy `
+     -Id "authorizationPolicy" `
+     -PermissionGrantPolicyIdsAssignedToDefaultUserRole @("microsoft-user-default-legacy")
+  ```
 
-> [!IMPORTANT]
-> The following information is for an upcoming feature which will allow group owners to grant applications access to their groups' data. When this capability is released, it will be enabled by default. Although this feature is not yet released widely, you can use these instructions to disable the capability in advance of its release.
+  > [!WARNING]
+  > This option allows all users to consent to any permission which does not require admin consent, for any application. Instead, Microsoft recommends allowing user consent only for apps from verified publishers.
+
+## Configure permission classifications (preview)
 
-Group owners can authorize applications (for example, applications published by third-party vendors) to access your organization's data associated with a group. For example, a team owner (who is the owner of the Office 365 Group for the team) can allow an app to read all Teams messages in the team, or list the basic profile of a group's members.
+Permission classifications allow you to identify the impact different permissions have, according to your organization's policies and risk evaluations. For example, permission classifications can be used in consent policies to identify the set of permissions which users are allowed to consent to.
 
 > [!NOTE]
-> Independent of this setting, a group owner is always allowed to add other users or apps directly as a group owners.
+> Currently, the only the "Low impact" permission classification is supported. In the future, additional levels of classification will be supported. Only delegated permissions which do not require admin consent can be classified as "Low impact".
+
+### Classify permissions using the Azure portal
+
+1. Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator](../users-groups-roles/directory-assign-admin-roles.md#global-administrator--company-administrator).
+2. Select **Azure Active Directory** > **Enterprise applications** > **Consent and permissions** > **Permission classifications**.
+3. Choose **Add permissions** to classify another permission as "Low impact". Select the API and then select the delegated permission(s).
+
+In this example, we've classified the minimum set of permission required for single sign-on:
+
+![Permission classifications](./media/configure-user-consent/configure-permission-classifications.png)
+
+> [!TIP]
+> The minimum permissions needed to do basic single sign on are `openid`, `profile`, `User.Read` and `offline_access`, for the Microsoft Graph API. With these permissions an app can read the profile details of the signed-in user, and can maintain this access even when the user is not longer using the app.
+
+### Classify permissions using PowerShell
+
+You can use the latest Azure AD PowerShell Preview module ([AzureADPreview](https://docs.microsoft.com/powershell/module/azuread/?view=azureadps-2.0-preview)) to classify permissions using PowerShell.
+
+Permission classifications are configured on the **ServicePrincipal** object of the API which publishes the permissions.
+
+To read the current permission classifications for an API:
+
+1. Retrieve the **ServicePrincipal** object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:
+
+   ```powershell
+   $api = Get-AzureADServicePrincipal `
+       -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"
+   ```
+
+2. Read the delegated permission classifications for the API:
+
+   ```powershell
+   Get-AzureADMSServicePrincipalDelegatedPermissionClassification `
+       -ServicePrincipalId $api.ObjectId | Format-Table Id, PermissionName, Classification
+   ```
+
+To classify a permission as "Low impact":
+
+1. Retrieve the **ServicePrincipal** object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:
+
+   ```powershell
+   $api = Get-AzureADServicePrincipal `
+       -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"
+   ```
+
+2. Find the delegated permission you would like to classify:
+
+   ```powershell
+   $delegatedPermission = $api.OAuth2Permissions | Where-Object { $_.Value -eq "User.ReadBasic.All" }
+   ```
+
+3. Set the permission classification using the permission name and ID:
+
+   ```powershell
+   Add-AzureADMSServicePrincipalDelegatedPermissionClassification `
+      -ServicePrincipalId $api.ObjectId `
+      -PermissionId $delegatedPermission.Id `
+      -PermissionName $delegatedPermission.Value `
+      -Classification "low"
+   ```
+
+To remove a delegated permission classification:
+
+1. Retrieve the **ServicePrincipal** object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:
+
+   ```powershell
+   $api = Get-AzureADServicePrincipal `
+       -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"
+   ```
+
+2. Find the delegated permission classification you wish to remove:
+
+   ```powershell
+   $classifications = Get-AzureADMSServicePrincipalDelegatedPermissionClassification `
+       -ServicePrincipalId $api.ObjectId
+   $classificationToRemove = $classifications | Where-Object {$_.PermissionName -eq "User.ReadBasic.All"}
+   ```
+
+3. Delete the permission classification:
+
+   ```powershell
+   Remove-AzureADMSServicePrincipalDelegatedPermissionClassification `
+       -ServicePrincipalId $api.ObjectId `
+       -Id $classificationToRemove.Id
+   ```
+
+## Configure group owner consent to apps accessing group data
+
+Group owners can authorize applications (for example, applications published by third-party vendors) to access your organization's data associated with a group. For example, a team owner in Microsoft Teams can allow an app to read all Teams messages in the team, or list the basic profile of a group's members.
+
+You can configure which users are allowed to consent to apps accessing their groups' data, or you can disable this feature.
+
+### Configure group owner consent using the Azure portal
+
+1. Sign in to the [Azure portal](https://portal.azure.com) as a [Global Administrator](../users-groups-roles/directory-assign-admin-roles.md#global-administrator--company-administrator).
+2. Select **Azure Active Directory** > **Enterprise applications** > **Consent and permissions** > **User consent settings**.
+3. Under **Group owner consent for apps accessing data** select the option you'd like to enable.
+4. Click **Save** to save your settings.
+
+In this example, all group owners are allowed to consent to apps accessing their groups' data:
+
+![Permission classifications](./media/configure-user-consent/configure-group-owner-consent.png)
 
 ### Configure group owner consent using PowerShell