Share via

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

  • Artigo

Neste artigo, você saberá como dar consentimento em nome de um único usuário usando o PowerShell.

Quando um usuário dá consentimento em seu próprio nome, os seguintes eventos ocorrem com mais frequência:

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

  2. Para cada API à qual o aplicativo requer acesso, uma permissão delegada concedida a essa API é criada em relação às permissões que são necessárias ao aplicativo. O acesso é concedido em nome do usuário. Uma concessão de permissão delegada autoriza um aplicativo a acessar uma API em nome de um usuário quando esse usuário entra.

  3. O usuário recebe o aplicativo cliente. Atribuir o aplicativo ao usuário faz com que o aplicativo seja 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 dar consentimento a um aplicativo em nome de um usuário, você precisa:

  • Uma conta de usuário com função privilegiada de administrador, administrador de aplicativos ou administrador de aplicativos em nuvem

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

  • A ID do aplicativo para o qual você está dando consentimento. Para fins deste artigo, o nomearemos de aplicativo cliente.
  • As permissões de API que o aplicativo cliente exige. Descubra a ID do aplicativo da API e as IDs de permissão ou valores de declaração.
  • O nome de usuário ou a ID de objeto do usuário em nome dos quais o acesso é concedido.

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

Para fornecer consentimento a um aplicativo em nome de um usuário usando o PowerShell do Microsoft Graph, você precisa entrar como pelo menos um Administrador de Aplicativos 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 fornecer consentimento a um aplicativo em nome de um usuário usando a API do Microsoft Graph, entre no Explorador de gráficos como pelo menos um Administrador de Aplicativos de Nuvem.

Será necessário consentir com as seguintes permissões:

Application.ReadWrite.All, Directory.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All.

No exemplo a seguir, você concederá 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 empresarial do recurso é o Microsoft Graph com a ID de objeto 11112222-bbbb-3333-cccc-4444dddd5555. O Microsoft Graph define as permissões delegadas, User.Read.All e Group.Read.All. O consentType é Principal, indicando que você está consentindo em nome de um único usuário no locatário. A ID do objeto do aplicativo empresarial cliente é 00001111-aaaa-2222-bbbb-3333cccc4444. A principalId do usuário é aaaaaaaa-bbbb-cccc-1111-222222222222.

Cuidado

Portanto, tenha cuidado! As permissões concedidas programaticamente não estão sujeitas a revisão nem confirmação. Elas entram em vigor imediatamente.

  1. Recupere todas as permissões delegadas definidas pelo Microsoft Graph (o aplicativo de recurso) em seu aplicativo de 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 solicitação a seguir.

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants

Request body
{
   "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
   "consentType": "Principal",
   "resourceId": "11112222-bbbb-3333-cccc-4444dddd5555",
   "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
   "scope": "User.Read.All Group.Read.All"
}

  3. Confirme se você deu consentimento ao usuário executando a solicitação a seguir.

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '00001111-aaaa-2222-bbbb-3333cccc4444' 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 de Meus Aplicativos do usuário. No exemplo a seguir, resourceId representa o aplicativo cliente ao qual o usuário está sendo atribuído. O usuário receberá a função de aplicativo padrão, que é 00000000-0000-0000-0000-000000000000.

        POST /servicePrincipals/resource-servicePrincipal-id/appRoleAssignedTo

    {
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "resourceId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
    "appRoleId": "00000000-0000-0000-0000-000000000000"
    }

Próximas etapas