Uwierzytelnianie użytkowników i uzyskiwanie tokenów dla agentów interaktywnych

Agenci interakcyjni podejmują akcje w imieniu użytkowników. Aby bezpiecznie działać w imieniu użytkowników, agent uwierzytelnia użytkownika, uzyskuje zgodę na wymagane uprawnienia i uzyskuje tokeny dostępu dla podrzędnych interfejsów API. W tym artykule przedstawiono kompleksowe uwierzytelnianie i przepływ pozyskiwania tokenów dla agenta interaktywnego:

  1. Udzielanie uprawnień za pośrednictwem uprawnień dziedziczych lub zgody.
  2. Uwierzytelnij użytkownika i uzyskaj token dostępu.
  3. Zweryfikuj token i wyodrębnij oświadczenia użytkownika.
  4. Uzyskaj tokeny dla podrzędnych interfejsów API za pomocą przepływu On-Behalf-Of (OBO).

Uwaga / Notatka

W tym artykule opisano agentów interaktywnych, którzy działają w imieniu zalogowanych użytkowników przy użyciu przepływu OBO. Jeśli agent potrzebuje własnej tożsamości przypominającej użytkownika (scenariusz cyfrowego pracownika), zobacz Konta użytkowników agenta i przepływ OAuth konta użytkownika agenta.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

  • Strategia tożsamości agenta. Zapisz identyfikator aplikacji szablonu tożsamości agenta (identyfikator klienta).
  • Tożsamość agenta.
  • Aplikacja kliencka zarejestrowana w Microsoft Entra do obsługi uwierzytelniania użytkowników.
  • Znajomość przepływu kodu autoryzacji OAuth 2.0.
  • Możliwość uruchomienia internetowego interfejsu API w ASP.NET Core, jeśli planujesz użyć przykładów dotyczących sprawdzania poprawności tokenu i OBO w tym artykule.

W przypadku autoryzacji administratora potrzebne są również następujące elementy:

Zanim agent będzie mógł działać w imieniu użytkownika, użytkownik lub administrator musi wyrazić zgodę na wymagane uprawnienia. Istnieją dwa podejścia do udzielania uprawnień:

  • Uprawnienia dziedziczone: Wstępnie autoryzuj uprawnienia w szablonie, aby tożsamości agentów automatycznie je dziedziczyły.
  • Zażądaj zgody: zarejestruj URI przekierowania i poproś użytkowników lub administratorów o wyrażenie zgody za pośrednictwem żądania OAuth albo użyj punktu końcowego zgody administratora.

Używanie uprawnień dziedziczylnych

Skonfiguruj uprawnienia dziedziczone w strategii tożsamości agenta, aby wstępnie uwierzytelnić podstawowy zestaw delegowanych zakresów i ról aplikacji. Tożsamości agenta utworzone na podstawie strategii automatycznie dziedziczą te uprawnienia bez interakcyjnych monitów o wyrażenie zgody. Aby uzyskać więcej informacji, zobacz Konfigurowanie uprawnień dziedzicznych dla szablonów tożsamości agenta.

Aby zażądać zgody w przepływie OAuth, schemat tożsamości agenta musi najpierw zostać skonfigurowany z identyfikatorem URI przekierowania. W przypadku schematów identyfikator URI przekierowania musi być typu aplikacja internetowa. W przeciwieństwie do adresów URI przekierowania w rejestracjach aplikacji adres URI przekierowania w blueprintcie nie może być używany do uzyskiwania tokenów delegowanych uprawnień. Tylko response_type=none jest obsługiwane w żądaniu OAuth2, co oznacza, że żądanie jedynie rejestruje zgodę i nie są zwracane żadne tokeny.

Zarejestruj identyfikator URI przekierowania

Aby zaktualizować URI przekierowania w planie tożsamości agenta, najpierw należy uzyskać token dostępu z delegowanym uprawnieniem AgentIdentityBlueprint.ReadWrite.All. Następnie wyślij żądanie PATCH do obiektu aplikacji dla szablonu tożsamości agenta:

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Aby agent mógł działać w imieniu użytkownika, użytkownik musi wyrazić zgodę na wymagane uprawnienia. Żądanie zgody użytkownika nie zwraca tokenu. Zamiast tego rejestruje, że użytkownik przyznał agentowi uprawnienia do działania w ich imieniu. Pozyskiwanie tokenu odbywa się w obszarze Uwierzytelnianie użytkownika i żądanie tokenu.

Ważna

Użyj identyfikatora klienta tożsamości agenta w parametrze client_id, a nie identyfikatora szablonu tożsamości agenta.

Aby wyświetlić monit o zgodę użytkownika, skonstruuj adres URL autoryzacji i przekieruj użytkownika do niego. Agent może przedstawić ten adres URL na różne sposoby, na przykład jako link w wiadomości czatu.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Gdy użytkownik otworzy ten adres URL, Microsoft Entra ID wyświetli monit o zalogowanie się i udzielenie zgody. Po wyrażeniu zgody użytkownik zostanie przekierowany z powrotem do URI przekierowania.

Kluczowe parametry w adresie URL autoryzacji zgody użytkownika to:

  • client_id: identyfikator klienta tożsamości agenta (a nie identyfikator klienta szablonu tożsamości agenta).
  • response_type: ustaw wartość na none , ponieważ to żądanie zezwala tylko na wyrażenie zgody. Pozyskiwanie tokenu odbywa się przy użyciu response_type=code w sekcji Uwierzytelnij użytkownika i zażądaj tokenu.
  • redirect_uri: musi dokładnie odpowiadać identyfikatorowi URI przekierowania skonfigurowanemu w szablonie tożsamości agenta.
  • scope: Określ wymagane uprawnienia delegowane (na przykład User.Read).
  • state: opcjonalny parametr do utrzymania stanu między żądaniem a wywołaniem zwrotnym.

Aby uzyskać więcej informacji na temat pojęć dotyczących autoryzacji protokołu OAuth, zobacz Uprawnienia i zgody w platformie tożsamości Microsoft.

Agenty mogą również poprosić administratora Microsoft Entra ID o autoryzację, a administrator może udzielić agentowi zgody w imieniu wszystkich użytkowników dzierżawcy. Zgoda administratora może być wymagana w zależności od ustawień zgody skonfigurowanych w dzierżawie.

Aby udzielić zgody administratora dla całej dzierżawy, należy skierować administratora pod następujący adres URL. Użyj identyfikatora tożsamości agenta w parametrze client_id .

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

Gdy administrator udzieli zgody, uprawnienia mają zastosowanie do całej dzierżawy. Użytkownicy nie muszą ponownie wyrażać zgody.

Uwaga / Notatka

Skonfiguruj adres URI przekierowania w blueprintcie i uwzględnij parametr state w żądaniu zgody. Po udzieleniu zgody użytkownik jest przekierowywany do adresu URI przekierowania, gdzie można wyświetlić potwierdzenie. Punkt końcowy może używać parametru state, aby śledzić fakt udzielenia uprawnienia. W przypadku agentów z jedną dzierżawą możesz też ponowić próbę żądania tokenu do momentu udzielenia zgody, ponieważ identyfikator dzierżawy jest już znany.

Uwierzytelnianie użytkownika i żądanie tokenu

Po udzieleniu zgody aplikacja kliencka (na przykład frontend lub aplikacja mobilna) inicjuje żądanie kodu autoryzacji OAuth 2.0, aby uzyskać token, w którym parametr audience jest ustawiony na schemat tożsamości agenta. W tym kroku client_id oznacza własny identyfikator zarejestrowanej aplikacji klienta, a nie tożsamość agenta ani szablon tożsamości agenta.

Uwaga / Notatka

redirect_uri w tym żądaniu odnosi się do rejestracji aplikacji klienckiej, a nie do adresu URI przekierowania planu skonfigurowanego w poprzednim kroku wyrażania zgody.

  1. Przekieruj użytkownika do punktu końcowego autoryzacji Microsoft Entra ID przy użyciu następujących parametrów:

    GET https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

  2. Gdy użytkownik się zaloguje, twoja aplikacja otrzyma kod autoryzacji pod przekierowanym URI. Wymień kod autoryzacji na token dostępu:

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

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>

    client_secret Dołącz parametr tylko w przypadku korzystania z poufnego klienta.

    Odpowiedź JSON zawiera token dostępu, który może służyć do uzyskiwania dostępu do interfejsu API agenta.

Weryfikowanie tokenu dostępu

Internetowy interfejs API musi zweryfikować przychodzący token dostępu, zanim agent będzie mógł działać. Zawsze używaj zatwierdzonej biblioteki do weryfikowania tokenów. Nie zapisuj własnego kodu weryfikacji tokenu.

  1. Zainstaluj pakiet NuGet Microsoft.Identity.Web:

    dotnet add package Microsoft.Identity.Web

  2. W projekcie internetowego interfejsu API ASP.NET Core zaimplementuj uwierzytelnianie Microsoft Entra ID:

    // Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

  3. Skonfiguruj poświadczenia uwierzytelniania w appsettings.json pliku:

    Ostrzeżenie

    Tajne klucze klienta nie powinny być używane jako poświadczenia klienta w środowiskach produkcyjnych dla szablonów tożsamości agenta ze względu na zagrożenia bezpieczeństwa. Zamiast tego należy użyć bezpieczniejszych metod uwierzytelniania, takich jak poświadczenia tożsamości federacyjnej (FIC) z tożsamościami zarządzanymi lub certyfikatami klienta. Te metody zapewniają zwiększone zabezpieczenia, eliminując konieczność przechowywania poufnych wpisów tajnych bezpośrednio w ramach konfiguracji aplikacji.

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

Aby uzyskać więcej informacji na temat Microsoft.Identity.Web, zobacz dokumentację Microsoft.Identity.Web.

Weryfikowanie oświadczeń użytkowników

Po weryfikacji tokenu dostępu agent może zidentyfikować użytkownika i przeprowadzić kontrole autoryzacji. Poniższa przykładowa trasa interfejsu API wyodrębnia oświadczenia użytkowników z tokenu dostępu i zwraca je w odpowiedzi interfejsu API:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Uzyskiwanie tokenów dla podrzędnych interfejsów API

Gdy agent interakcyjny zweryfikuje token użytkownika, może zażądać tokenów dostępu w celu wywołania podrzędnych interfejsów API w imieniu użytkownika. Przepływ On-Behalf-Of (OBO) umożliwia agentowi:

  • Odbieranie tokenu dostępu od klienta.
  • Wymień go na nowy token dostępu dla API niższego poziomu, takiego jak Microsoft Graph.
  • Użyj tego nowego tokenu, aby uzyskać dostęp do chronionych zasobów w imieniu oryginalnego użytkownika.

Biblioteka Microsoft.Identity.Web upraszcza implementację OBO przez automatyczne obsługiwanie wymiany tokenów, więc nie trzeba ręcznie implementować przepływu, postępując zgodnie z protokołem.

  1. Zainstaluj wymagane pakiety NuGet:

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

  2. W projekcie internetowego interfejsu API ASP.NET Core zaktualizuj implementację uwierzytelniania Microsoft Entra ID:

    // 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)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

  3. W interfejsie API agenta należy wymienić przychodzący token dostępu użytkownika dla nowego tokenu dostępu dla tożsamości agenta. Microsoft.Identity.Web weryfikuje przychodzący token dostępu i obsługuje wymianę tokenów w imieniu:

    app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

Pod maską przepływ OBO obejmuje dwie wymiany tokenów: najpierw strategia tożsamości agenta uzyskuje token wymiany przy użyciu poświadczeń klienta, a następnie tożsamość agenta wymienia ten token wraz z tokenem dostępu użytkownika dla tokenu interfejsu API podrzędnego. Aby zapoznać się z pełnym przewodnikiem po protokole, w tym formatami żądań HTTP i szczegółami weryfikacji tokenu, zobacz przepływ w imieniu agenta (On-behalf-of flow in agents).

Treści powiązane

Dowiedz się więcej o tokenach agenta i powiązanych interfejsach API:

  • Last updated on