Usar a conta de usuário de um agente com Microsoft 365

A maioria dos agentes autônomos deve fazer chamadas a APIs usando a identidade do agente e permissões de aplicativo. Crie uma conta de usuário do agente somente quando uma carga de trabalho do Microsoft 365 exigir um objeto de usuário.

A conta de usuário de um agente é uma identidade de usuário dedicada para o agente. Não é o usuário com sessão iniciada de um agente interativo. Cada conta tem uma relação um-para-um com uma identidade de agente.

Determinar se o agente precisa de um objeto de usuário

Scenario A conta de usuário de um agente é necessária? Guidance
Chamar uma API que dá suporte a permissões de aplicativo No Use a identidade do agente e o acesso somente de aplicativo.
Adicionar o agente como membro de uma equipe de Microsoft Teams Yes A associação de equipe é atribuída aos usuários do diretório. Consulte adicionar membros a uma equipe.
Dê ao agente sua própria caixa de correio Exchange Online Yes Uma caixa de correio é provisionada para um objeto de usuário. Consulte como criar caixas de correio de usuário no Exchange Online.
Compartilhar um item SharePoint ou OneDrive diretamente com o agente como usuário individual Yes Use a conta de usuário do agente como destinatária do compartilhamento. Confira o compartilhamento de arquivos e pastas.
Usar um serviço de Microsoft 365 licenciado por usuário Yes Atribua apenas as licenças exigidas pelo serviço. Confira a atribuição de licenças aos usuários.

Não crie a conta de usuário de um agente apenas porque o agente é executado sem uma pessoa presente. Se o serviço de destino der suporte a permissões de aplicativo ou controles de acesso de aplicativo específicos à carga de trabalho, use a identidade do agente.

Conceder acesso

  1. Crie a conta de usuário de um agente e associe-a à identidade do agente.
  2. Atribua à conta apenas as licenças de Microsoft 365 necessárias.
  3. Adicione a conta à equipe necessária, provisione sua caixa de correio ou compartilhe os recursos de SharePoint necessários seguindo a documentação do serviço na tabela anterior.
  4. Conceda permissões delegadas à identidade do agente para os escopos de Microsoft 365 que a carga de trabalho requer, como Mail.ReadWrite ou Files.ReadWrite. A identidade do agente usa essas permissões delegadas quando se autentica como a conta de usuário do agente.

Criar o objeto de usuário não concede acesso a um time, caixa de correio, site, arquivo ou API. Conclua em separado a atribuição específica para a carga de trabalho.

Autenticar como a conta de usuário do agente

O fluxo da conta de usuário do agente não envolve um usuário conectado. Use WithAgentUserIdentity para identificar a conta de usuário dedicada. Microsoft.Identity.Web.AgentIdentities executa a troca de token de ID do agente.

Este exemplo usa a troca de tokens blueprint-to-child. Reutilize a instalação do pacote e a configuração de runtime, incluindo Microsoft.Identity.Web.AgentIdentities, AddAgentIdentities()aquisição de token, um cliente HTTP e um cache de token. Configurar a ID e a credencial do cliente do blueprint no runtime; passe a ID do cliente da identidade do agente filho e sua conta de usuário associada para WithAgentUserIdentity. Não substitua a configuração somente de aplicativo de instância única, que omite esse registro de Exchange de ID do Agente.

O código a seguir é um fragmento de ponto de extremidade, não um host completo. Mesclar suas using diretivas na parte superior de Program.cs e colocar seu mapeamento antes de app.Run(). Configure a política de autorização de entrada AgentUser antes de expor o ponto de extremidade da caixa de correio. Resolva o agente e a conta da configuração de aplicativo confiável, não dos valores fornecidos pelo chamador.

Identifique a conta de usuário do agente pelo UPN:

using System.Net.Http.Headers;
using System.Security.Claims;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

app.MapGet("/mailbox", async (
    IAuthorizationHeaderProvider authorizationHeaderProvider,
    IHttpClientFactory httpClientFactory) =>
{
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity("<agent-identity-client-id>", "<agent-user-upn>");

    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            ["https://graph.microsoft.com/.default"],
            options,
            new ClaimsPrincipal());

    HttpClient client = httpClientFactory.CreateClient();
    client.DefaultRequestHeaders.Authorization =
        AuthenticationHeaderValue.Parse(authorizationHeader);

    using HttpResponseMessage response =
        await client.GetAsync("https://graph.microsoft.com/v1.0/me/messages");
    response.EnsureSuccessStatusCode();

    return Results.Content(
        await response.Content.ReadAsStringAsync(),
        "application/json");
})
.RequireAuthorization("AgentUser");

Ou identifique a conta por ID do objeto:

var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity("<agent-identity-client-id>", Guid.Parse("<agent-user-object-id>"));

Passe new ClaimsPrincipal() porque nenhum usuário está conectado. A identidade do usuário é proveniente WithAgentUserIdentity, não do contexto da solicitação. Conceda à conta de usuário do agente somente as permissões delegadas de que a carga de trabalho precisa. Não implemente a troca de tokens diretamente.

Para o modelo de protocolo e as restrições de segurança, consulte Protocolos OAuth no ID do agente Microsoft Entra. Para obter a referência completa da API, consulte Microsoft. Identity.Web no GitHub.

Para um autor de chamada de entrada autorizado, uma chamada /mailbox bem-sucedida retorna as mensagens do usuário agente configurado, e não a caixa de correio do chamador. Uma coleção de mensagens vazia pode ser válida. Se a chamada falhar, verifique a associação identidade-conta, a concessão delegada e o provisionamento da caixa de correio do Exchange separadamente. O exemplo gera uma exceção diante de um status de falha de um serviço downstream, em vez de encaminhar esse status para o chamador original.

Para recursos apenas para teste, siga Excluir a conta de usuário de um agente depois de remover qualquer acesso específico da carga de trabalho que você criou. Não exclua uma caixa de correio compartilhada ou uma conta.

Próxima etapa

Gerenciar a conta de usuário do agente