Chame uma Microsoft Graph API a partir de um agente usando .NET

Este artigo explica como chamar uma Microsoft Graph API a partir de um agente usando as identidades dos agentes ou a conta de utilizador de um agente.

Para chamar uma API a partir de um agente, é necessário obter um token de acesso que o agente possa usar para se autenticar à API. Recomendamos usar o Microsoft.Identity.Web SDK para .NET para chamar as suas APIs web. Este SDK simplifica o processo de aquisição e validação de tokens. Para outros idiomas, use o Microsoft Entra agent SDK para ID do agente.

Pré-requisitos

  • Uma identidade de agente com permissões apropriadas para chamar a API de destino. Precisas de um utilizador para o fluxo em nome dele.
  • A conta de utilizador de um agente com permissões apropriadas para chamar a API de destino.

Faça uma chamada a uma API do Microsoft Graph

  1. Instala o Microsoft. Identity.Web.GraphServiceClient que trata da autenticação do Graph SDK e do Microsoft. Identity.Web.AgentIdentities para adicionar suporte a identidades de agentes.

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

  2. Adicione o suporte para Microsoft Graph e identidades de agentes na 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 em appsettings.json.

    Advertência

    Os segredos do cliente não devem ser usados como credenciais do cliente em ambientes de produção para modelos de identidade de agentes por motivos de segurança. Em vez disso, utilize métodos de autenticação mais seguros, como credenciais de identidade federada (FIC) com identidades geridas ou certificados de cliente. Estes métodos proporcionam maior segurança ao eliminar a necessidade de armazenar segredos sensíveis diretamente na configuração da sua aplicação.

    {
  "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 pode obter o GraphServiceClient ao injetá-lo no seu serviço ou junto do fornecedor e ligar para Microsoft Graph.

  • Para as identidades dos agentes, pode adquirir um token exclusivo para aplicação (agentes autónomos) ou um token em nome do utilizador (agentes interativos) usando o WithAgentIdentity método. Para tokens apenas de app, defina a RequestAppToken propriedade para true. Para tokens delegados em nome do utilizador, não defina a propriedade RequestAppToken nem a defina explicitamente para 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 identificar as identidades das contas de utilizador do agente, pode especificar o Nome Principal do Utilizador (UPN) ou a Identidade do Objeto (OID), 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