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 de Autenticação Microsoft Entra ID (sidecar).

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 on-behalf-of.
  • A conta de usuário de um agente com permissões apropriadas para chamar a API de destino.

Chamar uma API do Microsoft 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.AspNetCore.Authentication.OpenIdConnect;
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": "<your-tenant-id>",
    "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"]
    }
  }
}

    Note

    Configure apenas as permissões do Microsoft Graph de que seu agente precisa e verifique se as Scopes que você define correspondem aos recursos do Graph que seu código acessa. Esses exemplos usam User.Read e User.ReadBasic.All; chamar outros recursos requer suas permissões correspondentes.

  4. Agora você pode obter o GraphServiceClient injetando-o em seu serviço ou no provedor de serviços e chamar o 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 on-behalf-of delegados do usuário, não defina a propriedade RequestAppToken ou defina-a explicitamente como false.

    using Microsoft.Graph;
using Microsoft.Identity.Web;

// 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 usersAppOnly = await graphServiceClient.Users
    .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 usersOnBehalfOfUser = await graphServiceClient.Users
    .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.

      using Microsoft.Graph;
using Microsoft.Identity.Web;

// 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 meByOid = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

Conteúdo relacionado

  • Last updated on