Utilize serviços do Azure a partir do seu agente usando o .NET SDK do Azure

Este artigo orienta-o sobre como chamar os serviços do Azure a partir do seu agente. Para autenticar em serviços Azure como Armazenamento do Azure ou Azure Key Vault usando identidades de agentes, use a classe MicrosoftIdentityTokenCredential de Microsoft. Identidade.Web. Azure. A classe MicrosoftIdentityTokenCredential implementa a interface TokenCredential da SDK do Azure, permitindo uma integração perfeita entre Microsoft. Identity.Web e SDK do Azure clientes.

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.

Passos de implementação

1. Instala o pacote de integração Azure e o Microsoft. Identity.Web.AgentIdentities para adicionar suporte a identidades de agentes.

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

2. Instale o pacote SDK do Azure que pretende usar, por exemplo, Armazenamento do Azure:

   dotnet add package Azure.Storage.Blobs
   

3. Configure os seus serviços para adicionar suporte a credenciais do token Azure:

   using Microsoft.Identity.Web;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Add authentication
   builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
       .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
       .EnableTokenAcquisitionToCallDownstreamApi()
       .AddInMemoryTokenCaches();
   
   // Add Azure token credential support
   builder.Services.AddMicrosoftIdentityAzureTokenCredential();
   
   builder.Services.AddControllersWithViews();
   var app = builder.Build();
   app.UseAuthentication();
   app.UseAuthorization();
   app.MapControllers();
   app.Run();
   

4. Configure opções de credenciais de token do Azure 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": "<your-tenant>",
       "ClientId": "<agent-blueprint-id>",
   
      // Other client creedentials available. See <https://aka.ms/ms-id-web/client-credentials>
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "your-client-secret"
         }
       ]   
     }
   }
   

5. Adquira uma credencial de token do fornecedor de serviços e utilize-a com clientes do SDK do Azure.

   1. 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.

      using Microsoft.Identity.Web;
      
      public class AgentService
      {
          private readonly MicrosoftIdentityTokenCredential _credential;
      
          public AgentService(MicrosoftIdentityTokenCredential credential)
          {
              _credential = credential;
          }
      
          // Call Azure service with the agent identity for app only scenario
          public async Task<List<string>> ListBlobsForAgentAsync(string agentIdentity)
          {
              // Configure for agent identity
              string agentIdentity = "agent-identity-guid";
              _credential.Options.WithAgentIdentity(agentIdentity);
              _credential.Options.RequestAppToken = true;
      
              var blobClient = new BlobServiceClient(
                  new Uri("https://myaccount.blob.core.windows.net"),
                  _credential);
      
              var container = blobClient.GetBlobContainerClient("agent-data");
              var blobs = new List<string>();
      
              await foreach (var blob in container.GetBlobsAsync())
              {
                  blobs.Add(blob.Name);
              }
      
              return blobs;
          }
      
          // Call Azure service with the agent identity for on-behalf of user scenario
          public async Task<List<string>> ListBlobsForAgentAsync(string agentIdentity)
          {
              // Configure for agent identity
              var blobClient = new BlobServiceClient(
                  new Uri("https://myaccount.blob.core.windows.net"));
      
              var container = blobClient.GetBlobContainerClient("agent-data");
              var blobs = new List<string>();
      
              await foreach (var blob in container.GetBlobsAsync())
              {
                  blobs.Add(blob.Name);
              }
      
              return blobs;
          }
      }
      

   2. Também pode adquirir um token para a conta de utilizador de um agente. Para isso, pode usar o Nome Principal do Utilizador (UPN) ou a Identidade do Objeto (OID) para identificar a conta de utilizador do agente.

      Para o ID do objeto:

      using Microsoft.Identity.Web;
      
      public class AgentService
      {
          private readonly MicrosoftIdentityTokenCredential _credential;
      
          public AgentService(MicrosoftIdentityTokenCredential credential)
          {
              _credential = credential;
          }
      
          // Use object ID to identify the agent's user account
          public async Task<List<string>> ListBlobsForAgentAsync(string agentIdentity)
          {
              // Configure for agent identity
              string agentIdentity = "agent-identity-guid";
              string userOid = "user-object-id";
              _credential.Options.WithAgentUserIdentity(agentIdentity, userOid);
      
              var blobClient = new BlobServiceClient(
                  new Uri("https://myaccount.blob.core.windows.net"),
                  _credential);
      
              var container = blobClient.GetBlobContainerClient("agent-data");
              var blobs = new List<string>();
      
              await foreach (var blob in container.GetBlobsAsync())
              {
                  blobs.Add(blob.Name);
              }
      
              return blobs;
          }
      
          // Use UPN to identify the agent's user account\
          public async Task<List<string>> ListBlobsForAgentAsync(string agentIdentity)
          {
              // Configure for agent identity
              string agentIdentity = "agent-identity-guid";
              string userUpn = "user@contoso.com";
      
              _credential.Options.WithAgentUserIdentity(agentIdentity, userUpn);
      
              var blobClient = new BlobServiceClient(
                  new Uri("https://myaccount.blob.core.windows.net"),
                  _credential);
      
              var container = blobClient.GetBlobContainerClient("agent-data");
              var blobs = new List<string>();
      
              await foreach (var blob in container.GetBlobsAsync())
              {
                  blobs.Add(blob.Name);
              }
      
              return blobs;
          }
      }
      

Conteúdo relacionado

• Chamar APIs personalizadas
• Liga Microsoft Graph