Muokkaa

Configure permission classifications

  • Artikkeli

In this article, you learn how to configure permissions classifications in Microsoft Entra ID. Permission classifications allow you to identify the impact that different permissions have according to your organization's policies and risk evaluations. For example, you can use permission classifications in consent policies to identify the set of permissions that users are allowed to consent to.

Three permission classifications are supported: "Low", "Medium" (preview), and "High" (preview). Currently, only delegated permissions that don't require admin consent can be classified.

The minimum permissions needed to do basic sign-in are openid, profile, email, and offline_access, which are all delegated permissions on the Microsoft Graph. With these permissions an app can read details of the signed-in user's profile, and can maintain this access even when the user is no longer using the app.

Prerequisites

To configure permission classifications, you need:

  • An Azure account with an active subscription. Create an account for free.
  • One of the following roles: Global Administrator, Application Administrator, or Cloud Application Administrator

Manage permission classifications

Tip

Steps in this article might vary slightly based on the portal you start from.

Follow these steps to classify permissions using the Microsoft Entra admin center:

  1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
  2. Browse to Identity > Applications > Enterprise applications > Consent and permissions > Permission classifications.
  3. Choose the tab for the permission classification you'd like to update.
  4. Choose Add permissions to classify another permission.
  5. 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

You can use the latest Azure AD PowerShell, to classify permissions. Permission classifications are configured on the ServicePrincipal object of the API that publishes the permissions.

Run the following command to connect to Azure AD PowerShell. To consent to the required scopes, sign in as at least a Cloud Application Administrator.

Connect-AzureAD

List the current permission classifications using Azure AD PowerShell

  1. Retrieve the ServicePrincipal object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:

    $api = Get-AzureADServicePrincipal `
    -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"

  2. Read the delegated permission classifications for the API:

    Get-AzureADMSServicePrincipalDelegatedPermissionClassification `
    -ServicePrincipalId $api.ObjectId | Format-Table Id, PermissionName, Classification

Classify a permission as "Low impact" using Azure AD PowerShell

  1. Retrieve the ServicePrincipal object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:

    $api = Get-AzureADServicePrincipal `
    -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"

  2. Find the delegated permission you would like to classify:

    $delegatedPermission = $api.OAuth2Permissions | Where-Object { $_.Value -eq "User.ReadBasic.All" }

  3. Set the permission classification using the permission name and ID:

    Add-AzureADMSServicePrincipalDelegatedPermissionClassification `
   -ServicePrincipalId $api.ObjectId `
   -PermissionId $delegatedPermission.Id `
   -PermissionName $delegatedPermission.Value `
   -Classification "low"

Remove a delegated permission classification using Azure AD PowerShell

  1. Retrieve the ServicePrincipal object for the API. Here we retrieve the ServicePrincipal object for the Microsoft Graph API:

    $api = Get-AzureADServicePrincipal `
    -Filter "servicePrincipalNames/any(n:n eq 'https://graph.microsoft.com')"

  2. Find the delegated permission classification you wish to remove:

    $classifications = Get-AzureADMSServicePrincipalDelegatedPermissionClassification `
    -ServicePrincipalId $api.ObjectId
$classificationToRemove = $classifications | Where-Object {$_.PermissionName -eq "User.ReadBasic.All"}

  3. Delete the permission classification:

    Remove-AzureADMSServicePrincipalDelegatedPermissionClassification `
    -ServicePrincipalId $api.ObjectId `
    -Id $classificationToRemove.Id

You can use Microsoft Graph PowerShell, to classify permissions. Permission classifications are configured on the ServicePrincipal object of the API that publishes the permissions.

Run the following command to connect to Microsoft Graph PowerShell. To consent to the required scopes, sign in as at least a Cloud Application Administrator.

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

List current permission classifications for an API using Microsoft Graph PowerShell

  1. Retrieve the servicePrincipal object for the API:

    $api = Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'"

  2. Read the delegated permission classifications for the API:

    Get-MgServicePrincipalDelegatedPermissionClassification -ServicePrincipalId $api.Id

Classify a permission as "Low impact" using Microsoft Graph PowerShell

  1. Retrieve the servicePrincipal object for the API:

    $api = Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'"

  2. Find the delegated permission you would like to classify:

    $delegatedPermission = $api.Oauth2PermissionScopes | Where-Object {$_.Value -eq "openid"}

  3. Set the permission classification:

    $params = @{ 
   PermissionId = $delegatedPermission.Id 
   PermissionName = $delegatedPermission.Value 
   Classification = "Low"
} 

New-MgServicePrincipalDelegatedPermissionClassification -ServicePrincipalId $api.Id -BodyParameter $params

Remove a delegated permission classification using Microsoft Graph PowerShell

  1. Retrieve the servicePrincipal object for the API:

    $api = Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'"

  2. Find the delegated permission classification you wish to remove:

    $classifications = Get-MgServicePrincipalDelegatedPermissionClassification -ServicePrincipalId $api.Id 

$classificationToRemove = $classifications | Where-Object {$_.PermissionName -eq "openid"}

  3. Delete the permission classification:

Remove-MgServicePrincipalDelegatedPermissionClassification -DelegatedPermissionClassificationId $classificationToRemove.Id   -ServicePrincipalId $api.id

To configure permissions classifications for an enterprise application, sign in to Graph Explorer as at least a Cloud Application Administrator.

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

Run the following queries on Microsoft Graph explorer to add a delegated permissions classification for an application.

List current permission classifications for an API using Microsoft Graph API

List current permission classifications for an API using the following Microsoft Graph API call.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')/delegatedPermissionClassifications

Classify a permission as "Low impact" using Microsoft Graph API

In the following example, we classify the permission as "low impact".

Add a delegated permission classification for an API using the following Microsoft Graph API call.

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')/delegatedPermissionClassifications
Content-type: application/json

{
   "permissionId": "b4e74841-8e56-480b-be8b-910348b18b4c",
   "classification": "low"
}

Remove a delegated permission classification using Microsoft Graph API

Run the following query on Microsoft Graph explorer to remove a delegated permissions classification for an API.

DELETE https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')/delegatedPermissionClassifications/QUjntFaOC0i-i5EDSLGLTAE

Next steps