以编程方式授予或撤销 API 权限

当以 entra ID Microsoft向客户端应用授予 API 权限时,权限授予将记录为可以像访问、更新或删除任何其他数据一样的对象。 使用 Microsoft Graph 直接创建权限授予是 交互式许可 的编程替代方法,可用于组织中的自动化方案、批量管理或其他自定义操作。

本文介绍如何使用 Microsoft Graph 为应用授予和撤销应用角色。 应用角色(也称为 应用程序权限直接访问权限)允许应用使用自己的标识调用 API。 详细了解 应用程序权限

警告

注意! 以编程方式授予的权限不受评审或确认的约束。 它们立即生效。

先决条件

若要完成这些说明,需要以下资源和特权:

  • 有效的Microsoft Entra 租户。
  • 在委派上下文中运行本文中的请求。 必须完成以下步骤:
    • 以有权在租户中创建应用程序的用户身份登录到 API 客户端(例如 Graph 资源管理器 )。 通过管理员配置 的应用同意策略,在租户中,创建权限授予的权限可能会受到限制或受到控制。
    • 在登录的应用中,代表登录用户同意 Application.Read.AllAppRoleAssignment.ReadWrite.All 委托的权限。 无需代表组织同意。
    • 获取向其授予应用角色的客户端服务主体的对象 ID。 在本文中,客户端服务主体由 ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94标识。 在 Microsoft Entra 管理中心,展开“标识”菜单,展开“>应用程序”>,选择“企业应用程序>”“应用应用程序”以查找客户端服务主体。 选择它,然后在 “概述 ”页上复制“对象 ID”值。

警告

已授予 AppRoleAssignment.ReadWrite.All 权限的应用只能由相应的用户访问。

步骤 1:获取资源服务主体的 appRoles

必须先确定公开要授予的应用角色的资源服务主体,然后才能授予应用角色。 应用角色在服务主体的 appRoles 对象中定义。 在本文中,将使用租户中的 Microsoft Graph 服务主体作为资源服务主体。

请求

以下请求检索租户中由 Microsoft Graph 服务主体定义的应用角色。

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,appRoles

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,appRoles)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "appRoles": [
                {
                    "allowedMemberTypes": [
                        "Application"
                    ],
                    "description": "Allows the app to read user profiles without a signed in user.",
                    "displayName": "Read all users' full profiles",
                    "id": "df021288-bdef-4463-88db-98f22de89214",
                    "isEnabled": true,
                    "origin": "Application",
                    "value": "User.Read.All"
                }
            ]
        }
    ]
}

步骤 2:向客户端服务主体授予应用角色

在此步骤中,向应用授予由 Microsoft Graph 公开的应用角色,从而导致 应用角色分配。 在步骤 1 中,Microsoft Graph 的对象 ID 为 7ea9e944-71ce-443d-811c-71e8047b557a ,应用角色 User.Read.All 由 ID df021288-bdef-4463-88db-98f22de89214标识。

请求

以下请求授予客户端应用 (ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94 的主体) ID df021288-bdef-4463-88db-98f22de89214 的应用角色,该角色由 ID 7ea9e944-71ce-443d-811c-71e8047b557a的资源服务主体公开。

注意

如果使用 Python SDK,请导入以下库:

from msgraph.generated.models.app_role_assignment import AppRoleAssignment
from msgraph.generated.models.service_principal import ServicePrincipal
POST https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo
Content-Type: application/json

{
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo/$entity",
    "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
    "deletedDateTime": null,
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
    "createdDateTime": "2022-05-18T15:37:21.8215423Z",
    "principalDisplayName": "My application",
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "principalType": "ServicePrincipal",
    "resourceDisplayName": "Microsoft Graph",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
}

确认应用角色分配

若要验证将角色分配给资源服务主体的主体,请运行以下请求。

请求

GET https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo

响应

响应对象包括对资源服务主体的应用角色分配的集合,并包括你在前面的请求中创建的应用角色分配。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo",
    "value": [
        {
            "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
            "deletedDateTime": null,
            "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
            "createdDateTime": "2022-05-18T15:37:21.8997216Z",
            "principalDisplayName": "My application",
            "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "principalType": "ServicePrincipal",
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
        }
    ]
}

步骤 3:从客户端服务主体撤消应用角色分配

请求

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo/47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M

响应

HTTP/1.1 204 No Content

总结

你已了解如何管理服务主体的应用角色授予。 这种使用 Microsoft Graph 授予权限的方法是另一种 交互式同意 方法,应谨慎使用。

本文介绍如何使用 Microsoft Graph 授予和撤销应用的委托权限。 委托的权限(也称为 作用域OAuth2 权限)允许应用代表已登录用户调用 API。 详细了解 委派权限

警告

注意! 以编程方式授予的权限不受评审或确认的约束。 它们立即生效。

先决条件

若要完成这些说明,需要以下资源和特权:

  • 有效的Microsoft Entra 租户。
  • 以用户身份运行本文中的请求。 必须完成以下步骤:
    • 以具有云应用程序管理员Microsoft Entra 角色的用户身份登录到 API 客户端(如 Graph 资源管理器),该角色是创建应用程序并授予租户中委派权限的最小特权角色。 通过管理员配置 的应用同意策略,在租户中,创建权限授予的权限可能会受到限制或受到控制。
    • 在登录的应用中,代表登录用户同意 Application.Read.AllDelegatedPermissionGrant.ReadWrite.All 委托的权限。 无需代表组织同意。
    • 获取代表用户向其授予委派权限的客户端服务主体的对象 ID。 在本文中,客户端服务主体由 ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94标识。 在 Microsoft Entra 管理中心,展开“标识”菜单,展开“>应用程序”>,选择“企业应用程序>”“应用应用程序”以查找客户端服务主体。 选择它,然后在 “概述 ”页上复制“对象 ID”值。

警告

已授予 DelegatedPermissionGrant.ReadWrite.All 权限的应用只能由相应的用户访问。

步骤 1:获取资源服务主体的委托权限

必须先确定公开要授予的委托权限的资源服务主体,然后才能授予委派权限。 委托的权限在服务主体的 oauth2PermissionScopes 对象中定义。 在本文中,将使用租户中的 Microsoft Graph 服务主体作为资源服务主体。

请求

以下请求检索租户中由 Microsoft Graph 服务主体定义的委托权限。

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,oauth2PermissionScopes)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Read all users' full profiles",
                    "id": "a154be20-db9c-4678-8ab7-66f6cc099a59",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on your behalf.",
                    "userConsentDisplayName": "Read all users' full profiles",
                    "value": "User.Read.All"
                },
                {
                    "adminConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user.  Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. ",
                    "adminConsentDisplayName": "Read all groups",
                    "id": "5f8c59db-677d-491f-a6b8-5f174b11ec1d",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on your behalf.  Also allows the app to read calendar, conversations, files, and other group content for all groups you can access.  ",
                    "userConsentDisplayName": "Read all groups",
                    "value": "Group.Read.All"
                }                
            ]
        }
    ]
}

步骤 2:代表用户向客户端服务主体授予委托权限

请求

在此步骤中,将代表用户向应用授予由 Microsoft Graph 公开的 委托权限,从而导致委派权限授予

  • 在步骤 1 中,租户中 Microsoft Graph 的对象 ID 为 7ea9e944-71ce-443d-811c-71e8047b557a
  • 委托的权限 User.Read.AllGroup.Read.All 分别由全局唯一 ID a154be20-db9c-4678-8ab7-66f6cc099a595f8c59db-677d-491f-a6b8-5f174b11ec1d 标识。
  • 主体是由 ID 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5标识的用户。
  • 客户端服务主体由 ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94标识。 这是服务主体的对象 ID而不是appId
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "scope": "User.Read.All Group.Read.All"
}

虽然前面的请求代表单个用户授予同意,但你可以选择代表租户中的所有用户授予同意。 请求正文类似于上一个请求正文,但有以下更改:

  • consentTypeAllPrincipals,表示你代表租户中的所有用户同意。
  • principalId 属性未提供,也可以是 null

代表所有用户授予同意的示例请求正文如下所示:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "AllPrincipals",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants/$entity",
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

如果向租户中的所有用户授予同意,则响应对象中的 consentType 将是 AllPrincipalsprincipalId 将为 null

确认权限授予

若要验证代表用户分配给服务主体的委托权限,请运行以下请求。

请求

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and principalId eq '3fbd929d-8c56-4462-851e-0eb9a7b3a2a5' and consentType eq 'Principal'

响应

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
    "value": [
        {
            "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "consentType": "Principal",
            "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
            "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "scope": "User.Read.All Group.Read.All"
        }
    ]
}

步骤 3:撤销代表用户授予服务主体的委托权限 [可选]

如果已代表用户向服务主体授予多个委派权限授予,则可以选择撤销特定授权或所有授权。 使用此方法可删除和撤销对分配给客户端服务主体的委托权限的同意。

  • 若要撤销一个或多个授权,请对 oauth2PermissionGrant 对象运行 PATCH 请求,并仅指定要保留在 scope 参数中的委托权限。
  • 若要撤销所有授权,请对 oauth2PermissionGrant 对象运行 DELETE 请求。

请求

以下请求撤销所有权限授予,并仅 User.Read.All 保留权限授予。 将删除权限,并撤销以前授予的同意。

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl
Content-Type: application/json

{
    "scope": "User.Read.All"
}

响应

HTTP/1.1 204 No Content

请求

以下请求将代表用户撤销对服务主体的所有权限授予。

DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl

响应

HTTP/1.1 204 No Content

总结

你向服务主体授予了 (或范围) 委派的权限。 这种使用 Microsoft Graph 授予权限的方法是 交互式同意 的替代方法,应谨慎使用。