Uwierzytelnianie i uzyskiwanie tokenów dla agentów autonomicznych

Zbierz poświadczenia skonfigurowane w strategii tożsamości agenta. Potrzebujesz jednego z następujących elementów:

• Zarządzana tożsamość (zalecane): identyfikator klienta tożsamości zarządzanej i token z usługi Azure Instance Metadata Service (IMDS).
• Certyfikat: odcisk palca certyfikatu lub plik PFX.
• Klucz tajny klienta (tylko do celów deweloperskich): wartość tajna.

Skonfiguruj Microsoft.Identity.Web do uwierzytelniania planu tożsamości agenta przy użyciu poświadczenia federacyjnego. W środowisku produkcyjnym użyj tożsamości zarządzanej jako poświadczenia tożsamości federacyjnej:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

Tylko w przypadku lokalnego programowania i testowania można użyć klucza tajnego klienta:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-client-id>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Użyj następującego żądania tokenu, aby uzyskać token dla strategii tożsamości agenta:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Z Microsoft.Identity.Web nie trzeba jawnie żądać tokenu dla szablonu tożsamości agenta. Microsoft. Identity.Web robi to za Ciebie.

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

Po uzyskaniu tokenu szkicu tożsamości agenta (T1), użyj go do żądania tokenu tożsamości agenta.

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Microsoft. Identity.Web obsługuje szczegóły protokołu pozyskiwania tokenu, pod warunkiem że używasz nowego services.AddAgentIdentities() w kolekcji usług podczas inicjowania aplikacji.

Zainicjuj aplikację:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

Użyj wzorca, .WithAgentIdentity() aby zażądać tokenów dostępu:

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

Po utworzeniu tokenu dostępu z niezbędnym uprawnieniem wykonaj następujące żądanie:

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "agentuserupn@tenant.onmicrosoft.com",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Aby użyć Microsoft.Identity.Web do utworzenia konta użytkownika agenta, wykonaj następujące kroki:

1. Dodaj następujące elementy do pliku konfiguracji:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/",
       "TenantId": "<your-tenant-id>",
       "ClientId": "<my-agent-blueprint-id>",
       "Scopes": "access_agent",
       "ClientCredentials": [
         {
           "SourceType": "SignedAssertionFromManagedIdentity",
           "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
         }
       ]
     },
   
     "DownstreamApis": {
       "agent-identity": {
         "BaseUrl": "https://graph.microsoft.com",
         "RelativePath": "/v1.0/users",
         "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
         "RequestAppToken": true
       }
     }
   }
   

2. Dodawanie wymaganych pakietów

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

3. Konfigurowanie usług.

   using Microsoft.Identity.Abstractions;
   using Microsoft.Identity.Web;
   using Microsoft.Identity.Web.Resource;
   using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
       .EnableTokenAcquisitionToCallDownstreamApi();
   builder.Services.AddAgentIdentities();
   builder.Services.AddInMemoryTokenCaches();
   
   var app = builder.Build();
   app.UseHttpsRedirection();
   app.UseAuthentication();
   app.UseAuthorization();
   app.Run();
   

4. Stwórz punkt końcowy do tworzenia konta użytkownika agenta.

   app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
   {
       try
       {
           // Get the service to call the downstream API (preconfigured in the appsettings.json file)
           IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
   
           var requestBody = new AgentIdUser
           {
               displayName = "my-agent-name",
               mailNickname = "my-agent-alias",
               userPrincipalName = "my-agent-email-address",
               accountEnabled = true,
               identityParentId = "<associated-agent-identity-id>"
           };
   
           // Call the downstream API (Graph) with a POST request to create an agent's user account
           var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
               "agent-identity",
               requestBody
           );
   
           return Results.Json(jsonResult);
       }
       catch (Exception ex)
       {
           return ex.Message;
       }
   })
   

Najpierw zażądaj tokenu jako strategii tożsamości agenta, zgodnie z opisem w temacie Żądanie tokenu dla strategii tożsamości agenta. Gdy masz już token planu tożsamości agenta, użyj tokenu planu tożsamości agenta, aby wystąpić o poświadczenie tożsamości federacyjnej (FIC) dla tożsamości agenta:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

To zwraca token wymiany (T2) dla tożsamości agenta. Użyj go w następnym żądaniu, aby uzyskać token delegowany dla konta użytkownika agenta:

POST https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

Zapewnia to delegowany token dostępu, którego można użyć do wywoływania Microsoft Graph jako konta użytkownika agenta. Możesz użyć user_id=<user-object-id> zamiast username=<UPN> identyfikatora użytkownika.

Microsoft. Identity.Web obsługuje pozyskiwanie tokenu. .WithAgentUserIdentity() Użyj wzorca, aby zażądać tokenów dostępu.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

    // Create a ClaimsPrincipal to enable token caching
    ClaimsPrincipal user = new ClaimsPrincipal();

    // Acquire a user token
    string authHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            scopes: ["https://graph.microsoft.com/.default"],
            options: options,
            user: user);

    return Results.Ok(authHeader);
});

Możesz również użyć głównej nazwy konta użytkownika agenta zamiast identyfikatora obiektu.