Conceder consentimento em nome de um único usuário usando o PowerShell

Neste artigo, você aprenderá a conceder consentimento em nome de um único usuário usando o PowerShell.

Quando um usuário concede consentimento para si mesmo, os seguintes eventos ocorrem com mais frequência:

  1. Uma entidade de serviço para o aplicativo cliente é criada, se ainda não existir. Uma entidade de serviço é a instância de um aplicativo ou serviço em seu locatário do Microsoft Entra. O acesso concedido ao aplicativo ou serviço está associado a esse objeto principal de serviço.

  2. Para cada API à qual o aplicativo requer acesso, uma concessão de permissão delegada a essa API é criada para as permissões de que o aplicativo precisa. O acesso é concedido em nome do utilizador. Uma concessão de permissão delegada autoriza um aplicativo a acessar uma API em nome de um usuário, quando esse usuário faz logon.

  3. O usuário recebe o aplicativo cliente. A atribuição do aplicativo ao usuário garante que o aplicativo esteja listado no portal Meus Aplicativos para esse usuário. O usuário pode revisar e revogar o acesso concedido em seu nome a partir do portal Meus Aplicativos.

Pré-requisitos

Para conceder consentimento a um aplicativo em nome de um usuário, você precisa:

  • Uma conta de usuário com Administrador Global, Administrador de Aplicativos ou Administrador de Aplicativos na Nuvem

Antes de começar, registre os seguintes detalhes no centro de administração do Microsoft Entra:

  • O ID do aplicativo para o qual você está concedendo consentimento. Para os fins deste artigo, nós o chamamos de aplicativo cliente.
  • As permissões de API que o aplicativo cliente exige. Descubra o ID do aplicativo da API e os IDs de permissão ou valores de declaração.
  • O nome de usuário ou ID de objeto do usuário em cujo nome o acesso é concedido.

Neste exemplo, usamos o Microsoft Graph PowerShell para conceder consentimento em nome de um único usuário. O aplicativo cliente é o Microsoft Graph Explorer e concedemos acesso à API do Microsoft Graph.

Para conceder consentimento a um aplicativo em nome de um usuário usando o Microsoft Graph PowerShell, você precisa entrar como pelo menos um Administrador de Aplicativo de Nuvem.

# The app for which consent is being granted. In this example, we're granting access
# to Microsoft Graph Explorer, an application published by Microsoft.
$clientAppId = "de8bc8b5-d9f9-48b1-a8ad-b748da725064" # Microsoft Graph Explorer

# The API to which access will be granted. Microsoft Graph Explorer makes API 
# requests to the Microsoft Graph API, so we'll use that here.
$resourceAppId = "00000003-0000-0000-c000-000000000000" # Microsoft Graph API

# The permissions to grant. Here we're including "openid", "profile", "User.Read"
# and "offline_access" (for basic sign-in), as well as "User.ReadBasic.All" (for 
# reading other users' basic profile).
$permissions = @("openid", "profile", "offline_access", "User.Read", "User.ReadBasic.All")

# The user on behalf of whom access will be granted. The app will be able to access 
# the API on behalf of this user.
$userUpnOrId = "user@example.com"

# Step 0. Connect to Microsoft Graph PowerShell. We need User.ReadBasic.All to get
#    users' IDs, Application.ReadWrite.All to list and create service principals, 
#    DelegatedPermissionGrant.ReadWrite.All to create delegated permission grants, 
#    and AppRoleAssignment.ReadWrite.All to assign an app role.
#    WARNING: These are high-privilege permissions!
Connect-MgGraph -Scopes ("User.ReadBasic.All Application.ReadWrite.All " `
                        + "DelegatedPermissionGrant.ReadWrite.All " `
                        + "AppRoleAssignment.ReadWrite.All")

# Step 1. Check if a service principal exists for the client application. 
#     If one doesn't exist, create it.
$clientSp = Get-MgServicePrincipal -Filter "appId eq '$($clientAppId)'"
if (-not $clientSp) {
   $clientSp = New-MgServicePrincipal -AppId $clientAppId
}

# Step 2. Create a delegated permission that grants the client app access to the
#     API, on behalf of the user. (This example assumes that an existing delegated 
#     permission grant does not already exist, in which case it would be necessary 
#     to update the existing grant, rather than create a new one.)
$user = Get-MgUser -UserId $userUpnOrId
$resourceSp = Get-MgServicePrincipal -Filter "appId eq '$($resourceAppId)'"
$scopeToGrant = $permissions -join " "
$grant = New-MgOauth2PermissionGrant -ResourceId $resourceSp.Id `
                                     -Scope $scopeToGrant `
                                     -ClientId $clientSp.Id `
                                     -ConsentType "Principal" `
                                     -PrincipalId $user.Id

# Step 3. Assign the app to the user. This ensures that the user can sign in if assignment
#     is required, and ensures that the app shows up under the user's My Apps portal.
if ($clientSp.AppRoles | ? { $_.AllowedMemberTypes -contains "User" }) {
    Write-Warning ("A default app role assignment cannot be created because the " `
                 + "client application exposes user-assignable app roles. You must " `
                 + "assign the user a specific app role for the app to be listed " `
                 + "in the user's My Apps access panel.")
} else {
    # The app role ID 00000000-0000-0000-0000-000000000000 is the default app role
    # indicating that the app is assigned to the user, but not for any specific 
    # app role.
    $assignment = New-MgServicePrincipalAppRoleAssignedTo `
          -ServicePrincipalId $clientSp.Id `
          -ResourceId $clientSp.Id `
          -PrincipalId $user.Id `
          -AppRoleId "00000000-0000-0000-0000-000000000000"
}

Para conceder consentimento a um aplicativo em nome de um usuário usando a API do Microsoft Graph, entre no Graph Explorer como pelo menos um Administrador de Aplicativo na Nuvem.

Você precisa consentir com as seguintes permissões:

Application.ReadWrite.All, , Directory.ReadWrite.AllDelegatedPermissionGrant.ReadWrite.All.

No exemplo a seguir, você concede permissões delegadas definidas por uma API de recurso a um aplicativo empresarial cliente em nome de um único usuário.

No exemplo, o aplicativo da empresa de recursos é o Microsoft Graph da ID 7ea9e944-71ce-443d-811c-71e8047b557ado objeto . O Microsoft Graph define as permissões User.Read.All delegadas e Group.Read.Allo . O consentType é Principal, indicando que você está consentindo em nome de um único usuário no locatário. O ID do objeto do aplicativo empresarial cliente é b0d9b9e3-0ecf-4bfd-8dab-9273dd055a941. O principalId do usuário é 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.

Atenção

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

  1. Recupere todas as permissões delegadas definidas pelo Microsoft graph (o aplicativo de recurso) em seu aplicativo locatário. Identifique as permissões delegadas que você deseja conceder ao aplicativo cliente. Neste exemplo, as permissões de delegação são User.Read.All e Group.Read.All

    GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes
    
  2. Conceda as permissões delegadas ao aplicativo empresarial cliente em nome do usuário executando a seguinte solicitação.

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    
    Request body
    {
       "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"
    }
    
  3. Confirme que você concedeu consentimento ao usuário executando a seguinte solicitação.

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and consentType eq 'Principal'
    
  4. Atribua o aplicativo ao usuário. Essa atribuição garante que o usuário possa entrar se a atribuição for necessária e garante que o aplicativo esteja disponível por meio do portal Meus Aplicativos do usuário. No exemplo a seguir, resourceIdrepresenta o aplicativo cliente ao qual o usuário está sendo atribuído. O usuário recebe a função de aplicativo padrão que é 00000000-0000-0000-0000-000000000000.

        POST /servicePrincipals/resource-servicePrincipal-id/appRoleAssignedTo
    
        {
        "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
        "resourceId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
        "appRoleId": "00000000-0000-0000-0000-000000000000"
        }
    

Próximos passos