Conceder consentimento em nome de um único utilizador com o PowerShell

Neste artigo, irá aprender a conceder consentimento em nome de um único utilizador através do PowerShell.

Quando um utilizador concede consentimento a si próprio, os seguintes eventos ocorrem com mais frequência:

1. É criado um principal de serviço para a aplicação cliente, se ainda não existir. Um principal de serviço é a instância de uma aplicação ou de um serviço no inquilino do Azure Active Directory (Azure AD). O acesso concedido à aplicação ou serviço está associado a este objeto do principal de serviço.

2. Para cada API à qual a aplicação necessita de acesso, é criada uma concessão de permissão delegada para essa API para as permissões necessárias pela aplicação, para acesso em nome do utilizador. Uma concessão de permissão delegada autoriza uma aplicação a aceder a uma API em nome de um utilizador, quando esse utilizador tiver iniciado sessão.

3. É atribuída ao utilizador a aplicação cliente. Atribuir a aplicação ao utilizador garante que a aplicação está listada no portal As Minhas Aplicações para esse utilizador, o que lhes permite rever e revogar o acesso concedido em seu nome.

Pré-requisitos

Para conceder consentimento a uma aplicação em nome de um utilizador, tem de:

• Uma conta de utilizador com Administrador Global, Administrador de Aplicações ou Administrador de Aplicações na Cloud

Conceder consentimento em nome de um único utilizador

Antes de começar, registe os seguintes detalhes do portal do Azure:

• O ID da aplicação para a aplicação que está a conceder consentimento. Para efeitos deste artigo, vamos chamá-lo de "aplicação cliente".
• As permissões de API que são necessárias pela aplicação cliente. Descubra o ID da aplicação da API e os IDs de permissão ou valores de afirmação.
• O nome de utilizador ou O ID do objeto do utilizador em cujo acesso em nome será concedido.

Neste exemplo, vamos utilizar o Microsoft Graph PowerShell para dar consentimento em nome de um único utilizador. A aplicação cliente é o Microsoft Graph Explorer e concedemos acesso ao microsoft Graph API.

# 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 dar consentimento a uma aplicação em nome de um utilizador, inicie sessão no Graph Explorer com uma das funções listadas na secção de pré-requisitos.

Terá de dar consentimento às seguintes permissões:

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

No exemplo seguinte, irá conceder permissões delegadas definidas por uma aplicação empresarial de recursos a uma aplicação empresarial cliente em nome de um único utilizador.

No exemplo, a aplicação empresarial de recursos é o Microsoft Graph do ID 7ea9e944-71ce-443d-811c-71e8047b557ado objeto . O Microsoft Graph define as permissões User.Read.All delegadas e Group.Read.All. O consentType é Principal, que indica que está a consentir em nome de um único utilizador no inquilino. O ID de objeto da aplicação empresarial cliente é b0d9b9e3-0ecf-4bfd-8dab-9273dd055a941. O principalId do utilizador é 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.

Atenção

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

1. Obtenha todas as permissões delegadas definidas pelo Microsoft Graph (a aplicação de recursos) na sua aplicação de inquilino. Identifique as permissões delegadas que irá conceder à aplicação 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 à aplicação empresarial cliente em nome do utilizador ao executar o seguinte pedido.

   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 concedeu consentimento ao utilizador ao executar o seguinte pedido.

   GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and consentType eq 'principal'
   

4. Atribua a aplicação ao utilizador. Isto garante que o utilizador pode iniciar sessão se a atribuição for necessária e garante que a aplicação está disponível através do portal de As Minhas Aplicações do utilizador. No exemplo seguinte, resourceIdrepresenta a aplicação cliente à qual o utilizador está a ser atribuído. Será atribuída ao utilizador a função de aplicação predefinida, 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"
       }
   

Passos seguintes

• Configurar o fluxo de trabalho de consentimento do administrador
• Configurar a forma como os utilizadores concedem consentimento às aplicações
• Permissões e consentimento na plataforma de identidades da Microsoft