Autenticare le identità dell'agente con Microsoft. Identity.Web

Non .NET? Per la documentazione del sidecar del contenitore Entra SDK, consultare la documentazione del contenitore Entra SDK. Il contenitore sidecar supporta le identità dell'agente su qualsiasi linguaggio e piattaforma.

Informazioni sulle identità degli agenti

Il pacchetto NuGet Microsoft.Identity.Web.AgentIdentities fornisce il supporto per le identità degli agenti in Microsoft Entra ID. Consente alle applicazioni di autenticare e acquisire in modo sicuro i token per le applicazioni agente, le identità degli agenti e le identità utente dell'agente, utili per agenti autonomi, agenti interattivi che agiscono per conto dell'utente e agenti che hanno la propria identità utente.

Questo pacchetto fa parte del Microsoft. Identity.Web suite di librerie ed è stata introdotta nella versione 3.10.0.

Esaminare i concetti chiave

I concetti seguenti sono essenziali per l'uso delle identità dell'agente.

Definire un progetto di identità dell'agente

Un modello di identità agente ha una registrazione speciale dell'applicazione in Microsoft Entra che dispone delle autorizzazioni per agire per conto delle identità agente o delle identità utente agente. È rappresentato dall'ID applicazione (ID client del progetto Di identità agente). Il progetto di identità dell'agente è configurato con credenziali (in genere certificati client FIC+MSI) e autorizzazioni per acquisire token da utilizzare per chiamare Graph. Questa è l'app sviluppata da te. Si tratta di un'applicazione client riservata, in genere un'API Web. Le uniche autorizzazioni che può avere sono mantenere (creare/eliminare) le identità degli agenti (usando il Microsoft Graph)

Creare un'identità di agente

Un'identità agente è un'entità servizio speciale in Microsoft Entra. Rappresenta un'identità creata dal progetto di identità dell'agente e autorizzata a rappresentare. Non ha credenziali autonome. Il progetto di identità dell'agente può acquisire token per conto dell'identità dell'agente, a condizione che l'utente o l'amministratore tenant abbia concesso il consenso per l'identità dell'agente agli ambiti corrispondenti. Gli agenti autonomi acquisiscono i token dell'applicazione per conto dell'identità dell'agente. Gli agenti interattivi chiamati con un token utente acquisiscono token utente per conto dell'agente.

Creare un'identità utente agente

Un'identità utente agente è un'identità dell'agente che può fungere anche da utente ,ad esempio un'identità dell'agente che avrebbe una propria cassetta postale o che segnala all'utente nella directory. Un'applicazione agente può acquisire un token per conto di un'identità utente agente.

Credenziali di identità federativa: cosa sapere

FIC è un meccanismo di attendibilità in Microsoft Entra che consente alle applicazioni di considerarsi attendibili usando token OIDC (OpenID Connect). Nel contesto delle identità dell'agente, le FIC vengono usate per stabilire una relazione di fiducia tra l'applicazione agente e le identità dell'agente, nonché tra le identità dell'agente e le identità utente dell'agente.

Altre informazioni

Per informazioni dettagliate sulle identità dell'agente Microsoft Entra, vedere Microsoft Entra Agent ID documentazione.

Installare il pacchetto

Eseguire il comando seguente per aggiungere il pacchetto NuGet al progetto:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Implementare le identità dell'agente

Seguire questa procedura per configurare e usare le identità dell'agente nell'applicazione.

1. Configurare i servizi

Prima di tutto, registrare i servizi necessari nell'applicazione:

// Add the core Identity Web services
services.AddTokenAcquisition();
services.AddInMemoryTokenCaches();
services.AddHttpClient();

// Add Microsoft Graph integration if needed.
// Requires the Microsoft.Identity.Web.GraphServiceClient package
services.AddMicrosoftGraph();

// Add Agent Identities support
services.AddAgentIdentities();

2. Configurare il progetto di identità dell'agente

Configurare l'applicazione del progetto di identità dell'agente con le credenziali necessarie usando appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-client-id",

    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertificateName"
      }

      // Or for Federation Identity Credential with Managed Identity:
      // {
      //   "SourceType": "SignedAssertionFromManagedIdentity",
      //   "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      // }
    ]
  }
}

In alternativa, se si preferisce, configurare a livello di codice:

// Configure the information about the agent application
services.Configure<MicrosoftIdentityApplicationOptions>(
    options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "agent-application-client-id";
        options.ClientCredentials = [
            CertificateDescription.FromStoreWithDistinguishedName(
                "CN=YourCertificateName", StoreLocation.LocalMachine, StoreName.My)
        ];
    });

Vedere https://aka.ms/ms-id-web/credential-description per tutti i modi per esprimere le credenziali.

In ASP.NET Core, utilizzare l'override di services.Configure fornendo uno schema di autenticazione. È anche possibile usare Microsoft. Identity.Web.Owin se si dispone di un'applicazione ASP.NET Core in OWIN (non consigliata per le nuove app) o anche creare un'applicazione daemon.

3. Usare le identità dell'agente

Scegliere il modello di acquisizione di token appropriato in base allo scenario dell'agente.

Acquisire i token per un'identità dell'agente

Usare questi modelli per acquisire token per le identità dell'agente in scenari autonomi o interattivi.

Acquisire i token dell'app per gli agenti autonomi

Affinché l'applicazione dell'agente autonomo acquisisca token solo app per un'identità dell'agente:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync("https://resource/.default", options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)

Acquisire i token utente per gli agenti interattivi

Affinché l'applicazione agente interattiva acquisisca i token utente per un'identità dell'agente per conto dell'utente che chiama l'API Web:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync(["https://resource/.default"], options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)

Acquisire i token per l'identità di un utente agente

Affinché l'applicazione agente acquisisca token per conto di un'identità utente agente, è possibile usare l'UPN dell'utente (Nome entità utente) o l'OID (ID oggetto).

Autenticarsi con UPN (Nome Principale Utente)

L'esempio seguente acquisisce un token utente specificando l'UPN dell'utente:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using UPN
string agentIdentity = "agent-identity-client-id";
string userUpn = "user@contoso.com";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userUpn);

// 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);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.

Eseguire l'autenticazione con OID (ID oggetto)

L'esempio seguente acquisisce un token utente specificando l'OID dell'utente:

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using OID
string agentIdentity = "agent-identity-client-id";
Guid userOid = Guid.Parse("e1f76997-1b35-4aa8-8a58-a5d8f1ac4636");
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userOid);

// 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);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.

4. Integrare con Microsoft Graph

Installare il pacchetto Microsoft.Identity.Web.AgentIdentities, che aggiunge il supporto per le identità degli agenti.

dotnet add package Microsoft.Identity.Web.AgentIdentities

Aggiungere il supporto per Microsoft Graph nella raccolta di servizi:

services.AddMicrosoftGraph();

È ora possibile ricevere un GraphServiceClient da parte del provider di servizi.

Chiamare Microsoft Graph con l'identità dell'agente

L'esempio seguente chiama Microsoft Graph API usando un'identità dell'agente:

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

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

Chiamare Microsoft Graph con l'identità utente dell'agente

È possibile usare UPN o OID con Microsoft Graph:

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

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

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

5. Integrare con le API downstream

Per chiamare altre API usando l'astrazione IDownstreamApi :

Installare il pacchetto Microsoft.Identity.Web.DownstreamApi che fornisce l'interfaccia di astrazione IDownstreamApi

dotnet add package Microsoft.Identity.Web.DownstreamApi

Aggiungere una DownstreamApis sezione nella configurazione specificando i parametri per l'API downstream:

"AzureAd":{
    // usual config
},
"DownstreamApis":{
   "MyApi":
   {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [ "https://myapi.domain.com/read", "https://myapi.domain.com/write" ]
   }
}

Aggiungere il supporto per le API downstream nella raccolta di servizi:

services.AddDownstreamApis(Configuration.GetSection("DownstreamApis"));

È ora possibile accedere a un IDownstreamApi servizio dal provider di servizi e chiamare l'API "MyApi" usando qualsiasi verbo HTTP. L'esempio seguente illustra la chiamata di API con l'identità dell'agente e l'identità utente dell'agente:

// Get the IDownstreamApi service
IDownstreamApi downstreamApi = serviceProvider.GetRequiredService<IDownstreamApi>();

// Call API with agent identity
var response = await downstreamApi.GetForAppAsync<string>(
    "MyApi",
    options => options.WithAgentIdentity(agentIdentity));

// Call API with agent user identity using UPN
var userResponse = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userUpn));

// Or using OID
var userResponseByOid = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userOid));

6. Integrare con Azure SDK

Per utilizzare gli SDK di Azure, usare la classe MicrosoftIdentityAzureCredential dal pacchetto NuGet Microsoft.Identity.Web.Azure.

Installare il pacchetto Microsoft.Identity.Web.Azure.

dotnet add package Microsoft.Identity.Web.Azure

Aggiungere il supporto per le credenziali del token Azure nella raccolta di servizi:

services.AddMicrosoftIdentityAzureTokenCredential();

È ora possibile ricevere un MicrosoftIdentityTokenCredential da parte del provider di servizi. Questa classe ha un membro Options a cui è possibile applicare il metodo .WithAgentIdentity() o .WithAgentUserIdentity().

Per altre informazioni, vedere integrazione Azure SDK.

7. Configurare HttpClient con MicrosoftIdentityMessageHandler

Per usare HttpClient direttamente con opzioni di autenticazione flessibili, usare il pacchetto Microsoft.Identity.Web.TokenAcquisition.

Nota: Il pacchetto Microsoft.Identity.Web.TokenAcquisition è già referenziato da Microsoft.Identity.Web.AgentIdentities.

Autenticare l'identità dell'agente con MicrosoftIdentityMessageHandler

L'esempio seguente configura un httpClient con l'autenticazione dell'identità dell'agente:

// Configure HttpClient with MicrosoftIdentityMessageHandler in DI
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://myapi.domain.com");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes= { "https://myapi.domain.com/.default" }
});

// Usage in your service or controller
public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = true;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Autenticare l'identità utente dell'agente con MicrosoftIdentityMessageHandler

L'esempio seguente invia una richiesta autenticata con un'identità utente agente:

public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    // Create request with agent user identity authentication
    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options =>
        {
            options.WithAgentUserIdentity(agentIdentity, userUpn);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

Configurare Manualmente HttpClient

È anche possibile configurare manualmente il gestore per un maggiore controllo:

// Get the authorization header provider
IAuthorizationHeaderProvider headerProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Create the handler with default options
var handler = new MicrosoftIdentityMessageHandler(
    headerProvider,
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://graph.microsoft.com/.default" }
    });

// Create HttpClient with the handler
using var httpClient = new HttpClient(handler);

// Make requests with per-request authentication options
var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.microsoft.com/v1.0/applications")
    .WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    });

var response = await httpClient.SendAsync(request);

Il MicrosoftIdentityMessageHandler offre un modo flessibile e componibile per aggiungere l'autenticazione al codice basato su HttpClient mantenendo al tempo stesso la compatibilità completa con i metodi di estensione Web identity Microsoft esistenti per le identità dell'agente.

Convalidare i token dagli identificativi dell'agente

Convalidare i token acquisiti per le identità dell'agente o le identità utente dell'agente allo stesso modo di qualsiasi API Web. Tuttavia, è anche possibile:

controllare se è stato rilasciato un token per un'identità dell'agente e per quale blueprint dell'agente.
```
HttpContext.User.GetParentAgentBlueprint()
```
restituisce il ClientId del blueprint dell'agente padre se il token viene emesso per un'identità dell'agente (o identità utente agente)
controllare se è stato emesso un token per un'identità utente dell'agente.
```
HttpContext.User.IsAgentUserIdentity()
```

Questi 2 metodi di estensione si applicano sia a ClaimsIdentity che a ClaimsPrincipal.

Verificare i prerequisiti

Assicurarsi di completare questi passaggi di configurazione prima di implementare le identità dell'agente.

Configurare la registrazione di Microsoft Entra

Configurazione dell'applicazione agente:

Registrare un'applicazione agente con Graph SDK
Aggiungere le credenziali client per l'applicazione agente
Concedere autorizzazioni API appropriate, ad esempio Application.ReadWrite.All per creare identità dell'agente

Configurazione di esempio in JSON:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertName"
      }
    ]
  }
}

Configurazione identità agente:
- Chiedere all'agente di creare un'identità dell'agente
- Concedere le autorizzazioni API appropriate in base alle esigenze dell'identità dell'agente
Autorizzazione utente:
- Per gli scenari di identità utente agente, assicurarsi che siano configurate le autorizzazioni utente appropriate.

Informazioni sul flusso di autenticazione

Sotto il cofano, il pacchetto Microsoft.Identity.Web.AgentIdentities:

Stabilisce l'attendibilità tra l'applicazione dell'agente e l'identità dell'agente e tra l'identità dell'agente e l'identità utente dell'agente, usando le credenziali di identità federate (FIC).
Acquisisce i token FIC usando il GetFicTokenAsync metodo
Usa i token FIC per autenticare l'identità dell'agente
Per le identità utente dell'agente, usa le estensioni MSAL per eseguire l'acquisizione di token utente

Risolvere i problemi comuni

Esaminare questi problemi comuni e le soluzioni quando si lavora con le identità dell'agente.

Risolvere i problemi noti

Missing FIC Configuration: Verificare che le credenziali di identità federata siano configurate correttamente in Microsoft Entra tra l'applicazione agente e l'identità dell'agente.
Problemi di autorizzazione: verificare che l'applicazione agente disponga di autorizzazioni sufficienti per gestire le identità dell'agente e che le identità dell'agente dispongano di autorizzazioni sufficienti per chiamare le API downstream.
Problemi di certificato: se si usa un certificato client, verificare che il certificato sia registrato nella registrazione dell'app, installato correttamente e accessibile dal codice dell'applicazione agente.
Errori di acquisizione dei token: abilitare la registrazione per diagnosticare gli errori di acquisizione dei token. Il codice seguente configura il log della console di livello debug.
```
services.AddLogging(builder => {
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});
```

Esplorare risorse aggiuntive

Documentazione di Microsoft Entra
documentazione di Microsoft Identity Web
Federazione delle identità di carichi di lavoro
documentazione Microsoft Graph SDK

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-29