Controlar o acesso a agentes com funções de app

As funções de aplicativo definem quem pode acessar um agente e o que eles podem fazer. Use-as para restringir operações do agente a usuários, grupos ou aplicativos cliente aprovados.

Neste artigo, você define uma função de acesso de entrada, atribui-a a um chamador e a aplica na API do agente. Onde você define a função depende se o agente usa um blueprint de instância única ou uma frota.

Pré-requisitos

  • Um blueprint e seu service principal da API do agente.
  • Um cliente de gerenciamento de Microsoft Graph autorizado para configuração de função. Para o gerenciamento delegado de instância única, o usuário conectado deve ser o proprietário da identidade do agente ou ter a função de Administrador de ID do Agente. Consulte Update servicePrincipal para obter as permissões de API aplicáveis.
  • Administrador de Aplicativos ou Administrador de Aplicativos na Nuvem para gerenciar atribuições de função de aplicativo de usuário e grupo.
  • AppRoleAssignment.ReadWrite.All e a permissão de leitura apropriada para atribuições programáticas.

Para a jornada de nuvem de instância única, a entidade de serviço da API é a identidade do agente, não uma entidade de blueprint. Use o ID do objeto como <agent-api-service-principal-object-id> nas solicitações deste artigo. Um blueprint de instância única não tem nenhum principal de blueprint. Para a jornada avançada da frota, use o blueprint principal da frota em vez disso; suas atribuições se aplicam em toda a frota.

Definir funções de app

Escolha o local de definição para o modo de instância:

Modo de instância Definir o perfil de entrada em Atribuir a função em
Instância única O aplicativo blueprint e a entidade de serviço do Agent ID, usando o mesmo GUID de função e valor. A entidade de segurança ID do agente.
Fleet O aplicativo Blueprint. O principal de blueprint que representa a API de frota.

Use um papel quando todos tiverem o mesmo nível de acesso. Por exemplo, use Agent.User para tarefas padrão e adicione Agent.Admin somente se você expor tarefas administrativas. Mantenha os valores de função estáveis porque suas políticas de autorização os verificam.

Declarar o papel no blueprint

Defina Agent.User na coleção appRoles do aplicativo blueprint. Para um agente de instância única, conclua a próxima seção para disponibilizar a mesma função em sua ID do Agente.

Leia o blueprint existente appRoles primeiro. A solicitação a seguir é para um blueprint sem papéis existentes. Para uma coleção existente, inclua as definições de função existentes que você pretende reter; a atualização appRoles substitui a coleção. Omita o campo origin somente leitura das solicitações.

Substitua <agent-user-role-id> por um novo GUID e salve-o para a etapa de atribuição:

PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>

{
  "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

Acesso de usuário de instância única

Para um agente de instância única, publique a mesma função de usuário diretamente na coleção do ID do agente appRoles. Use o mesmo GUID e valor que a declaração de blueprint, não um GUID de segunda função. A declaração somente blueprint não disponibiliza a função para atribuição na ID do Agente. A definição somente de entidade de serviço não conclui a configuração de blueprint usada neste procedimento.

Leia as funções existentes da ID do agente primeiro e mantenha suas definições na atualização. Para uma ID do Agente sem funções existentes, envie:

PATCH https://graph.microsoft.com/beta/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>

{
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

Essa é a configuração de função em dois objetos separados, não herança de permissões nem concessão de API downstream. Não crie uma entidade de blueprint para um agente de instância única.

A definição de service principal é compatível com User para usuários e grupos. Não adicione Application a essa solicitação: as funções atribuíveis a aplicativos cliente devem ser definidas em um objeto de aplicativo. Este procedimento de instância única abrange o acesso de usuário de entrada, não os chamadores somente de aplicativo. Consulte a referência de recurso appRole.

Acesso à frota

Para uma frota, use a declaração de blueprint sem a atualização da entidade de serviço de instância única. Inclua User em allowedMemberTypes para usuários ou grupos e Application para aplicativos cliente. Para o procedimento no nível do aplicativo, consulte Adicionar funções de aplicativo a um aplicativo. Use o principal do blueprint, não uma ID do agente filho, como o recurso para atribuições de entrada.

Verifique a função no principal do recurso

Antes de solicitar ou atribuir um papel, releia o blueprint com GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles e a entidade principal da API do agente com GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles. Use um cliente de gerenciamento autorizado, não o token de runtime do agente.

Confirme se a entidade de appRoles segurança contém a exata id da função e value, ou isEnabled seja true, e isso allowedMemberTypes inclui o tipo de atribuído pretendido.

Se uma atribuição retornar Permission being assigned was not found on application, verifique a definição da função na entidade de segurança do recurso e o resourceId e o appRoleId da atribuição. Para um agente de instância única, complete a definição direta acima se você definiu a função somente no blueprint. Não crie um principal de blueprint, substitua outro recurso ou remova a verificação da role da API. Continue somente depois que o principal pretendido expuser o papel.

Exigir uma atribuição de função de aplicativo

Defina appRoleAssignmentRequired no principal de serviço da API do agente. Quando a propriedade é true, Microsoft Entra ID emite um token de acesso para a API do agente apenas para usuários e aplicativos atribuídos.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "appRoleAssignmentRequired": true
}

Para obter mais informações, consulte a referência da API de atualização Microsoft Graph.

Atribuir uma função de aplicativo

Atribua a função de aplicativo a um usuário na entidade de serviço de API do agente:

POST https://graph.microsoft.com/v1.0/users/<user-object-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "principalId": "<user-object-id>",
  "resourceId": "<agent-api-service-principal-object-id>",
  "appRoleId": "<app-role-id>"
}

Use o GUID salvo quando você definiu Agent.User como <app-role-id>. Para um grupo, crie a atribuição por meio das atribuições de função de aplicativo do grupo. Para uma função de frota que permite Application, crie a atribuição de um aplicativo cliente por meio da entidade de serviço desse cliente. Em todos os casos, use a ID do objeto da entidade de serviço de API do agente como resourceId.

Aplicar funções de aplicativo na API do agente

Quando um usuário ou aplicativo atribuído obtém um token de acesso para a API do agente, Microsoft Entra ID inclui os valores de função de aplicativo atribuídos na declaração do roles token. A API do agente verifica essa declaração antes de permitir a operação solicitada.

Depois de configurar a autenticação e a validação de token, adicione uma política de autorização que exija a função de aplicativo:

Em Program.cs, mescle o registro da política em builder.Services.AddAuthorization antes de builder.Build(). Coloque o mapeamento de ponto de extremidade após o middleware de autenticação e autorização e antes app.Run(); as duas partes desse fragmento não são adjacentes em um aplicativo completo.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "AgentUser",
        policy => policy.RequireRole("Agent.User"));
});

app.MapPost("/tasks", () => Results.Accepted())
    .RequireAuthorization("AgentUser");

AddAuthorizationregistra os serviços de autorização ASP.NET Core. RequireRole verifica a identidade autenticada para o papel Agent.User. Microsoft.Identity.Web reconhece as funções de aplicativo do Microsoft Entra na declaração roles do token de acesso.

Chame UseAuthentication antes de UseAuthorization no pipeline de middleware, conforme mostrado no artigo de autenticação. Solicite um novo token de acesso depois de alterar uma atribuição. Ao solucionar problemas, verifique a atribuição na entidade de serviço da API do agente e a declaração roles do token.

Com um novo token para a API do agente e a função atribuída Agent.User , o exemplo POST /tasks retorna 202 Accepted. Sem um token, espere 401; um token de outra forma válido sem essa função será rejeitado com 403 se o locatário o emitir. Quando a atribuição é necessária, Microsoft Entra ID pode rejeitar a emissão de token ou de entrada antes que a solicitação chegue à sua API.