Conceder permissões de acesso a aplicativos a um agente autônomo

Os agentes geralmente precisam executar ações no Microsoft Graph e em outros serviços Web que exijam uma permissão de aplicativo do Microsoft Entra ID (representada como funções de aplicativo). Os agentes autônomos precisam solicitar essas permissões de um administrador da ID do Microsoft Entra. Este artigo explica o processo de solicitação de permissões de aplicativo de um administrador usando a identidade do agente criada nas etapas anteriores.

Há duas maneiras de conceder permissões de aplicação a um agente autônomo:

• Um administrador pode criar um appRoleAssignment usando APIs do Microsoft Graph ou o PowerShell.
• O agente pode direcionar o administrador para uma página de consentimento usando uma URL de consentimento do administrador.

Pré-requisitos

Antes de conceder permissões às identidades dos agentes, verifique se você tem:

• Uma identidade de agente criada (consulte Criar e excluir identidades do agente)
• Privilégios de administrador em seu locatário da ID do Microsoft Entra
• Noções básicas sobre as permissões específicas que seu agente requer

Criar uma atribuição de função de aplicativo por meio de APIs

Use as etapas a seguir para obter uma atribuição de função de aplicativo.

1. Obtenha um token de acesso com as permissões Application.Read.All delegadas e AppRoleAssignment.ReadWrite.All.

2. Obtenha a ID do objeto da entidade de serviço de recurso que você está tentando acessar. Por exemplo, para encontrar a ID do objeto do principal de serviço do Microsoft Graph:

   1. Acesse o centro de administração do Microsoft Entra.
   2. Acesse Entra ID -->Aplicativos Empresariais
   3. Filtrar por tipo de aplicativo == Aplicativos da Microsoft
   4. Pesquise Microsoft Graph.

3. Obtenha a ID exclusiva da função de aplicativo que você deseja atribuir.

4. Crie a atribuição de função do aplicativo:

   Microsoft Graph API

   POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
   Authorization: Bearer <token>
   Content-Type: application/json
   
   {
     "principalId": "<agent-identity-id>",
     "resourceId": "<microsoft-graph-sp-object-id>",
     "appRoleId": "<app-role-id>"
   }
   

   PowerShell do Microsoft Graph

   Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-test-tenant>
   
   # Get the service principal for Microsoft Graph (well-known app ID)
   $graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"
   
   # Get your application's service principal (replace with your app's client ID)
   $agentId = "<agent-identity-id>"
   
   # Find the App Role ID for "User.ReadBasic.All"
   $userReadBasicRole = $graphSp.AppRoles | Where-Object {
       $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
   }
   
   # Assign the app role
   New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
       -PrincipalId $agentId `
       -ResourceId $graphSp.Id `
       -AppRoleId $userReadBasicRole.Id
   

---

Solicitar autorização de um administrador de locatário

Para conceder permissões delegadas, crie a URL de autorização usada para solicitar uma ação do administrador. O parâmetro de função é usado para especificar as permissões de aplicativo solicitadas.

Certifique-se de usar o ID do cliente de identidade do agente na seguinte solicitação.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

As implementações do agente podem redirecionar o administrador para essa URL de várias maneiras, como incluí-la em uma mensagem enviada ao administrador em uma janela de chat. Quando o administrador é redirecionado para essa URL, ele é solicitado a entrar e conceder consentimento às permissões especificadas no parâmetro de escopo. No momento, você deve usar o URI de redirecionamento listado, que direciona o administrador para uma página em branco após a concessão de consentimento.

Depois de conceder ao aplicativo as permissões necessárias, solicite um novo token de acesso do agente para que as permissões entrem em vigor.

Conteúdo relacionado

• Referência de permissões do Microsoft Graph
• Permissões e consentimento na plataforma de identidade da Microsoft