Conceder ou revogar permissões de API programaticamente

Quando concede permissões de API a uma aplicação cliente no Microsoft Entra ID, as concessões de permissão são registadas como objetos que podem ser acedidos, atualizados ou eliminados como quaisquer outros dados. Utilizar o Microsoft Graph para criar concessões de permissão diretamente é uma alternativa programática ao consentimento interativo e pode ser útil para cenários de automatização, gestão em massa ou outras operações personalizadas na sua organização.

Neste artigo, vai aprender a conceder e revogar funções de aplicações para uma aplicação com o Microsoft Graph. As funções de aplicação, também denominadas permissões de aplicação ou permissões de acesso direto, permitem que uma aplicação chame uma API com a sua própria identidade. Saiba mais sobre as permissões de aplicação.

Cuidado

Cuidado! As permissões concedidas programaticamente não estão sujeitas a revisão ou confirmação. Produzem efeito imediatamente.

Pré-requisitos

Para concluir estas instruções, precisa dos seguintes recursos e privilégios:

  • Um inquilino válido do Microsoft Entra.
  • Execute os pedidos neste artigo num contexto delegado. Tem de concluir os seguintes passos:
    • Inicie sessão num cliente de API, como o Graph Explorer , como um utilizador com privilégios para criar aplicações no inquilino. Os privilégios para criar concessões de permissão podem ser limitados ou controlados no seu inquilino através de políticas de consentimento de aplicações configuradas pelo administrador.
    • Na aplicação na qual tem sessão iniciada, consenta as permissões Application.Read.All e AppRoleAssignment.ReadWrite.All delegated em nome do utilizador com sessão iniciada. Não precisa de dar consentimento em nome da sua organização.
    • Obtenha o ID de objeto do principal de serviço de cliente ao qual concede funções de aplicação. Neste artigo, o principal de serviço de cliente é identificado pelo ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. No centro de administração do Microsoft Entra, expanda o menu >Identidade expanda Aplicações> selecione Aplicações empresariais>Aplicações de aplicações para encontrar o principal de serviço de cliente. Selecione-o e, na página Descrição geral , copie o valor do ID do Objeto.

Cuidado

As aplicações a quem tenha sido concedida a permissão AppRoleAssignment.ReadWrite.All só devem ser acedidas por utilizadores adequados.

Passo 1: Obter as appRoles do principal de serviço de recursos

Antes de poder conceder funções de aplicação, primeiro tem de identificar o principal de serviço de recursos que expõe as funções de aplicação que pretende conceder. As funções de aplicação são definidas no objeto appRoles de um principal de serviço. Neste artigo, vai utilizar o principal de serviço do Microsoft Graph no seu inquilino como principal de serviço de recursos.

Solicitação

O pedido seguinte obtém as funções de aplicação definidas pelo principal de serviço do Microsoft Graph no inquilino.

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

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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"
                }
            ]
        }
    ]
}

Passo 2: Conceder uma função de aplicação a um principal de serviço de cliente

Neste passo, concede à sua aplicação uma função de aplicação que é exposta pelo Microsoft Graph, o que resulta numa atribuição de função de aplicação. No Passo 1, o ID de objeto do Microsoft Graph é 7ea9e944-71ce-443d-811c-71e8047b557a e a função User.Read.All da aplicação é identificada pelo ID df021288-bdef-4463-88db-98f22de89214.

Solicitação

O pedido seguinte concede à aplicação cliente (o principal do ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) uma função de aplicação do ID df021288-bdef-4463-88db-98f22de89214 que é exposta por um principal de serviço de recursos do ID 7ea9e944-71ce-443d-811c-71e8047b557a.

Observação

Se estiver a utilizar o SDK python, importe as seguintes bibliotecas:

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"
}

Resposta

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"
}

Confirmar a atribuição de função de aplicação

Para verificar os principais com atribuições de funções ao principal de serviço de recursos, execute o seguinte pedido.

Solicitação

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

Resposta

O objeto de resposta inclui uma coleção de atribuições de funções de aplicação ao principal de serviço de recursos e inclui a atribuição de função de aplicação que criou no pedido anterior.

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"
        }
    ]
}

Passo 3: Revogar uma atribuição de função de aplicação a partir de um principal de serviço de cliente

Solicitação

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

Resposta

HTTP/1.1 204 No Content

Conclusão

Aprendeu a gerir as concessões de funções de aplicação para um principal de serviço. Este método de conceder permissões com o Microsoft Graph é um consentimento interativo alternativo e deve ser utilizado com cuidado.

Neste artigo, vai aprender a conceder e revogar permissões delegadas para uma aplicação com o Microsoft Graph. As permissões delegadas, também denominadasâmbitos ou permissões OAuth2, permitem que uma aplicação chame uma API em nome de um utilizador com sessão iniciada. Saiba mais sobre as permissões delegadas.

Cuidado

Cuidado! As permissões concedidas programaticamente não estão sujeitas a revisão ou confirmação. Produzem efeito imediatamente.

Pré-requisitos

Para concluir estas instruções, precisa dos seguintes recursos e privilégios:

  • Um inquilino válido do Microsoft Entra.
  • Execute os pedidos neste artigo como um utilizador. Tem de concluir os seguintes passos:
    • Inicie sessão num cliente de API, como o Graph Explorer , como um utilizador com a função Administrador de Aplicações na Cloud Microsoft Entra, que é a função de privilégio mínimo para criar aplicações e conceder consentimento a permissões delegadas no inquilino. Os privilégios para criar concessões de permissão podem ser limitados ou controlados no seu inquilino através de políticas de consentimento de aplicações configuradas pelo administrador.
    • Na aplicação na qual iniciou sessão, consoante a aplicação Application.Read.All, DelegatedPermissionGrant.ReadWrite.Todas as permissões delegadas em nome do utilizador com sessão iniciada. Não precisa de dar consentimento em nome da sua organização.
    • Obtenha o ID de objeto do principal de serviço de cliente ao qual concede permissões delegadas em nome de um utilizador. Neste artigo, o principal de serviço de cliente é identificado pelo ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. No centro de administração do Microsoft Entra, expanda o menu >Identidade expanda Aplicações> selecione Aplicações empresariais>Aplicações de aplicações para encontrar o principal de serviço de cliente. Selecione-o e, na página Descrição geral , copie o valor do ID do Objeto.

Cuidado

As aplicações a quem tenha sido concedida a permissão DelegatedPermissionGrant.ReadWrite.All só devem ser acedidas por utilizadores adequados.

Passo 1: obter as permissões delegadas do principal de serviço de recursos

Antes de poder conceder permissões delegadas, primeiro tem de identificar o principal de serviço de recursos que expõe as permissões delegadas que pretende conceder. As permissões delegadas são definidas no objeto oauth2PermissionScopes de um principal de serviço. Neste artigo, vai utilizar o principal de serviço do Microsoft Graph no seu inquilino como principal de serviço de recursos.

Solicitação

O pedido seguinte obtém as permissões delegadas definidas pelo principal de serviço do Microsoft Graph no inquilino.

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

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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"
                }                
            ]
        }
    ]
}

Passo 2: Conceder uma permissão delegada ao principal de serviço de cliente em nome de um utilizador

Solicitação

Neste passo, concede à sua aplicação, em nome de um utilizador, uma permissão delegada que é exposta pelo Microsoft Graph, o que resulta numa concessão de permissão delegada.

  • No Passo 1, o ID de objeto do Microsoft Graph no inquilino é 7ea9e944-71ce-443d-811c-71e8047b557a
  • As permissões User.Read.All delegadas e Group.Read.All são identificadas pelos IDs exclusivos a154be20-db9c-4678-8ab7-66f6cc099a59 global e 5f8c59db-677d-491f-a6b8-5f174b11ec1d respetivamente.
  • O principal é um utilizador identificado pelo ID 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.
  • O principal de serviço do cliente é identificado pelo ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Este é o ID de objeto do principal de serviço e não o 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"
}

Embora o pedido anterior conceda consentimento em nome de um único utilizador, pode optar por conceder consentimento em nome de todos os utilizadores no inquilino. O corpo do pedido é semelhante ao corpo do pedido anterior, exceto com as seguintes alterações:

  • O consentType é AllPrincipals, que indica que está a consentir em nome de todos os utilizadores no inquilino.
  • A propriedade principalId não é fornecida ou pode ser null.

Um corpo de pedido de exemplo para conceder consentimento em nome de todos os utilizadores é o seguinte:

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"
}

Resposta

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"
}

Se concedeu consentimento a todos os utilizadores no inquilino, o consentType no objeto de resposta seria AllPrincipalse o principalId seria null.

Confirmar a concessão de permissão

Para verificar as permissões delegadas atribuídas ao principal de serviço em nome do utilizador, execute o seguinte pedido.

Solicitação

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'

Resposta

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"
        }
    ]
}

Passo 3: revogar as permissões delegadas concedidas a um principal de serviço em nome de um utilizador [Opcional]

Se tiver sido concedida a um principal de serviço várias concessões de permissão delegadas em nome de um utilizador, pode optar por revogar concessões específicas ou todas as concessões. Utilize este método para remover e revogar o consentimento das permissões delegadas que atribuiu ao principal de serviço de cliente.

  • Para revogar uma ou algumas concessões, execute um pedido PATCH no objeto oauth2PermissionGrant e especifique apenas as permissões delegadas a reter no parâmetro de âmbito .
  • Para revogar todas as concessões, execute um pedido DELETE no objeto oauth2PermissionGrant.

Solicitação

O pedido seguinte revoga todas as concessões de permissão e retém apenas a User.Read.All concessão de permissão. As permissões são removidas e o consentimento concedido anteriormente é revogado.

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

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

Resposta

HTTP/1.1 204 No Content

Solicitação

O pedido seguinte revoga todas as concessões de permissão para um principal de serviço em nome de um utilizador.

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

Resposta

HTTP/1.1 204 No Content

Conclusão

Concedeu permissões delegadas (ou âmbitos) a um principal de serviço. Este método de concessão de permissões com o Microsoft Graph é uma alternativa ao consentimento interativo e deve ser utilizado com cuidado.