Chamar Microsoft API do Graph de um agente usando .NET

Este artigo explica como chamar uma Microsoft API do Graph a partir de um agente usando identidades de agentes ou a conta de usuário de um agente.

Para chamar uma API de um agente, você precisa obter um token de acesso que o agente pode usar para se autenticar na API. É recomendável usar o SDK Microsoft.Identity.Web para .NET para chamar suas APIs web. Esse SDK simplifica o processo de aquisição e validação de tokens. Para outros idiomas, use o SDK do agente Microsoft Entra para o ID do agente.

Pré-requisitos

  • Uma identidade de agente com permissões apropriadas para chamar a API de destino. Você precisa de um usuário para o fluxo em nome.
  • A conta de usuário de um agente com permissões apropriadas para chamar a API de destino.

Chamar Microsoft API do Graph

  1. Instale o Microsoft. Identity.Web.GraphServiceClient que manipula a autenticação para o SDK do Graph e o Microsoft. Identity.Web.AgentIdentities pacote para adicionar suporte para identidades de agente.

    dotnet add package Microsoft.Identity.Web.GraphServiceClient
dotnet add package Microsoft.Identity.Web.AgentIdentities

  2. Adicione o suporte para Microsoft Graph e identidades de agente em sua coleção de serviços.

    using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication (web app or web API)
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Add Microsoft Graph support
builder.Services.AddMicrosoftGraph();

// Add Agent Identities support
builder.Services.AddAgentIdentities();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

  3. Configurar as opções de identidade do Graph e do agente no appsettings.json.

    Aviso

    Segredos do cliente não devem ser usados como credenciais de cliente em ambientes de produção para esquemas de identidade de agente devido a riscos de segurança. Em vez disso, use métodos de autenticação mais seguros, como fic (credenciais de identidade federadas) com identidades gerenciadas ou certificados de cliente. Esses métodos fornecem segurança aprimorada eliminando a necessidade de armazenar segredos confidenciais diretamente na configuração do aplicativo.

    {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": ["User.Read", "User.ReadBasic.All"]
    }
  }
}

  4. Agora você pode obter o GraphServiceClient injetando-o em seu serviço ou no provedor de serviços e chamar Microsoft Graph.

  • Para identidades de agente, você pode adquirir um token apenas de aplicativo (agentes autônomos) ou um token em nome de usuário (agentes interativos) usando o método WithAgentIdentity. Para tokens somente de aplicativo, defina a RequestAppToken propriedade como true. Para tokens delegados em nome do usuário, não defina a propriedade RequestAppToken ou defina-a explicitamente como false.

    // Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

string agentIdentity = "agent-identity-guid";

// Call Microsoft Graph APIs with the agent identity for app only scenario
var applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true; // Set to true for app only
    }));

// Call Microsoft Graph APIs with the agent identity for on-behalf of user scenario
var applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = false; // False to show it's on-behalf of user
    }));

    • Para as identidades da conta de usuário do agente, você pode especificar o User Principal Name (UPN) ou a Object Identity (OID) para identificar a conta de usuário do agente usando o método WithAgentUserIdentity.

      // Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

string agentIdentity = "agent-identity-guid";

// Call Microsoft Graph APIs with the agent's user account identity using UPN
string userUpn = "user-upn";
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userUpn)));

// Or using OID
string userOid = "user-object-id";
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

Conteúdo relacionado

  • Last updated on