Agentidentiteiten: autonome en interactieve agentpatronen

Agentidentiteiten maken geavanceerde verificatiescenario's mogelijk waarbij een agenttoepassing autonoom of namens gebruikers handelt. Door agentidentiteiten te gebruiken met de Microsoft Entra SDK voor AgentID, kunt u zowel autonome agents maken die werken in hun eigen context als interactieve agents die namens gebruikers handelen. Om deze scenario's te vergemakkelijken, ondersteunt de SDK specifieke queryparameters om agentidentiteiten en gebruikerscontexten op te geven.

Zie de documentatie Microsoft agent identity platform voor gedetailleerde richtlijnen over agentidentiteiten.

Overzicht

Agentidentiteiten ondersteunen twee primaire patronen:

  • Autonome agent: de agent werkt in een eigen toepassingscontext.
  • Interactieve agent: een interactieve agent werkt namens een gebruiker.

De SDK accepteert drie optionele queryparameters:

  • AgentIdentity - GUID van de agent-id.
  • AgentUsername - User Principal Name (UPN) voor specifieke gebruiker.
  • AgentUserId - Gebruikersobject-id (OID) voor specifieke gebruiker, als alternatief voor UPN.

Prioriteitsregels

AgentUsername en AgentUserId sluiten elkaar wederzijds uit. Aanvragen met beide parameters mislukken validatie, zoals beschreven in regel 2: wederzijdse exclusiviteit. Geef slechts één van deze parameters per aanvraag op.

configuratie van Microsoft Entra ID

Voordat u agentidentiteiten in uw toepassing configureert, moet u de benodigde onderdelen in Microsoft Entra ID instellen. Zie Register van een toepassing als u een nieuwe toepassing wilt registreren in Microsoft Entra ID tenant.

Vereisten voor agentidentiteiten

  1. Registratie van agentapplicatie:

    • Registreer de ouderagenttoepassing in Microsoft Entra ID.
    • API-machtigingen configureren voor downstream-API's.
    • Stel client-inloggegevens in (FIC+MSI, certificaat of sleutel).

  2. Configuratie van agentidentiteit:

    • Maak agentidentiteiten met behulp van de agentenblauwdruk.
    • Wijs de benodigde machtigingen toe aan agentidentiteiten.

  3. Toepassingsmachtigingen:

    • Toepassingsmachtigingen verlenen voor autonome scenario's.
    • Gedelegeerde machtigingen verlenen voor scenario's voor gebruikersdelegering.
    • Zorg ervoor dat waar nodig beheerderstoestemming wordt gegeven.

Zie de documentatie van het Microsoft agentidentiteitsplatform voor gedetailleerde stapsgewijze instructies voor het configureren van agentidentiteiten in Microsoft Entra ID.

Semantische regels

Om succesvol te authenticeren, moet u agentidentiteitsparameters correct gebruiken. De volgende regels bepalen het gebruik van AgentIdentity, AgentUsernameen AgentUserId parameters. Volg deze regels om validatiefouten te voorkomen die door de SDK worden geretourneerd.

Regel 1: Vereiste AgentIdentiteit

AgentUsername of AgentUserId moet worden gekoppeld aan AgentIdentity.

Als u opgeeft AgentUsername of AgentUserId zonder AgentIdentity, mislukt de aanvraag met een validatiefout.

# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com

Regel 2: Wederzijdse exclusiviteit

AgentUsername en AgentUserId zijn parameters die elkaar wederzijds uitsluiten.

U kunt niet beide AgentUsername en AgentUserId in dezelfde aanvraag opgeven. Als u beide parameters opgeeft, mislukt de aanvraag met een validatiefout.

# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Regel 3: Autonome versus interactieve

De combinatie van parameters bepaalt het verificatiepatroon:

Parameterwaarden Patroon Description
AgentIdentity alleen Autonome agent Hiermee verkrijgt u een applicatietoken voor de agentidentiteit
AgentIdentity + AgentUsername Interactieve agent Hiermee verwerft u het gebruikerstoken voor de opgegeven gebruiker (door UPN)
AgentIdentity + AgentUserId Interactieve agent Hiermee verkrijgt u een gebruikerstoken voor de opgegeven gebruiker (door Object ID).

Voorbeelden:

# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id

# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

Gebruikspatronen

Voor elk gebruikspatroon bepaalt de combinatie van parameters de verificatiestroom en het type token dat is verkregen.

Patroon 1: Autonome agent

De agenttoepassing wordt onafhankelijk uitgevoerd in een eigen toepassingscontext en haalt toepassingstokens op.

Scenario: Een batchverwerkingsservice die bestanden zelf verwerkt.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012

Tokenkenmerken:

  • Tokentype: Applicatietoken
  • Onderwerp (sub): object-ID van de agenttoepassing
  • Token gemaakt voor de identiteit van de agent
  • Machtigingen: Toepassingsmachtigingen die zijn toegewezen aan agentidentiteit

Gebruiksvoorbeelden:

  • Geautomatiseerde batchverwerking
  • Achtergrondtaken
  • Systeem-tot-systeembewerkingen
  • Geplande taken zonder gebruikerscontext

Patroon 2: Autonome gebruikersagent (op gebruikersnaam)

De agent wordt uitgevoerd namens een specifieke gebruiker die is geïdentificeerd door de UPN.

Scenario: Een AI-assistent die namens een gebruiker in een chattoepassing handelt.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com

Tokenkenmerken:

  • Tokentype: Gebruikerstoken
  • Onderwerp (sub): Object-id van gebruiker
  • Facet van agentidentiteit opgenomen in tokenclaims
  • Machtigingen: interactieve machtigingen die zijn gericht op de gebruiker

Gebruiksvoorbeelden:

  • Interactieve agenttoepassingen
  • AI-assistenten met gebruikersdelegering
  • Automatisering met gebruikersbereik
  • Gepersonaliseerde werkstromen

Patroon 3: Autonome gebruikersagent (op basis van object-ID)

De agent werkt namens een specifieke gebruiker die is geïdentificeerd door de object-id.

Scenario: Een werkstroomengine die gebruikersspecifieke taken verwerkt met behulp van opgeslagen gebruikers-id's.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321

Tokenkenmerken:

  • Tokentype: Gebruikerstoken
  • Onderwerp (sub): Object-id van gebruiker
  • Facet van agentidentiteit opgenomen in tokenclaims
  • Machtigingen: interactieve machtigingen die zijn gericht op de gebruiker

Gebruiksvoorbeelden:

  • Langlopende werkstromen met opgeslagen gebruikers-id's
  • Batchbewerkingen namens meerdere gebruikers
  • Systemen die object-id's gebruiken voor gebruikersreferenties

Patroon 4: Interactieve agent (handelen namens de gebruiker die het aanroept)

Een agentweb-API ontvangt een gebruikerstoken, valideert het en voert gedelegeerde aanroepen uit namens die gebruiker.

Scenario: Een web-API die fungeert als een interactieve agent die binnenkomende gebruikerstokens valideert en gedelegeerde aanroepen naar downstreamservices doet.

Stroom:

  1. De web-API van de agent ontvangt een gebruikerstoken van de aanroepende toepassing.
  2. Valideert het token via het /Validate eindpunt.
  3. Hiermee worden tokens voor downstream-API's verkregen door /AuthorizationHeader aan te roepen met alleen AgentIdentity en de binnenkomende autorisatieheader.
# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

Tokenkenmerken:

  • Tokentype: Gebruikers-token (OBO-stroom)
  • Onderwerp (sub): Object-id van oorspronkelijke gebruiker
  • Agent fungeert als intermediair voor de gebruiker
  • Machtigingen: interactieve machtigingen die zijn gericht op de gebruiker

Gebruiksvoorbeelden:

  • Web-API's die fungeren als agents
  • Interactieve agentservices
  • Agent-gebaseerde middleware die taken delegeert aan downstream-API's
  • Services die gebruikerscontext valideren en doorsturen

Patroon 5: Reguliere aanvraag (geen agent)

Wanneer u geen agentparameters opgeeft, gebruikt de SDK de identiteit van het binnenkomende token.

Scenario: Standaard on-behalf-of (OBO) flow zonder agentidentiteiten.

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

Tokenkenmerken:

  • Tokentype: is afhankelijk van het binnenkomende token en de configuratie
  • Maakt gebruik van standaard-OBO- of clientreferentiestroom
  • Geen facets voor agentidentiteit

Codevoorbeelden

De volgende codefragmenten laten zien hoe u de verschillende identiteitspatronen voor agents implementeert met behulp van verschillende programmeertalen en hoe u kunt communiceren met de SDK-eindpunten. De code laat zien hoe u niet-verwerkte aanroepen naar de SDK kunt verwerken om autorisatieheaders voor downstream-API-aanroepen te verkrijgen.

TypeScript: Autonome agent

const sidecarUrl = "http://localhost:5000";
const Agent ID = "12345678-1234-1234-1234-123456789012";

async function runBatchJob() {
  const response = await fetch(
    `${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
    {
      headers: {
        'Authorization': 'Bearer system-token'
      }
    }
  );
  
  const { authorizationHeader } = await response.json();
  // Use authorizationHeader for downstream API calls
}

Python: Agent met gebruikersidentiteit

import requests

sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"

response = requests.get(
    f"{sidecar_url}/AuthorizationHeader/Graph",
    params={
        "AgentIdentity": agent_id,
        "AgentUsername": user_email
    },
    headers={"Authorization": f"Bearer {system_token}"}
)

token = response.json()["authorizationHeader"]

TypeScript: Interactieve agent

async function delegateCall(userToken: string) {
  // Validate incoming token
  const validation = await fetch(
    `${sidecarUrl}/Validate`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  const claims = await validation.json();
  
  // Call downstream API on behalf of user
  const response = await fetch(
    `${sidecarUrl}/DownstreamApi/Graph`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  return await response.json();
}

C# met HttpClient

using System.Net.Http;

var httpClient = new HttpClient();

// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);

// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);

// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);

Foutscenario's

Wanneer u agentidentiteitsparameters onjuist configureert of onjuist gebruikt, retourneert de SDK validatiefouten. In de volgende secties worden veelvoorkomende foutscenario's en de bijbehorende antwoorden beschreven. Zie de gids voor probleemoplossing voor meer informatie over foutafhandeling.

Ontbrekende agentidentiteit met agentgebruikersnaam

Aanvraag:

GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

Antwoord:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

Zowel AgentUsername als AgentUserId opgegeven

Aanvraag:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

Antwoord:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

Ongeldige AgentUserId-indeling

Aanvraag:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid

Antwoord:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

Beste praktijken

  1. Invoer valideren: Valideer altijd agentidentiteitsparameters voordat u aanvragen indient.
  2. Gebruik object-id's indien beschikbaar: Object-id's zijn stabieler.
  3. Implementeer de juiste foutafhandeling: afhandelen van validatiefouten van agentidentiteit zonder problemen.
  4. Beveilig agentreferenties: bescherm de ID's en referenties van de agentidentiteitclient.
  5. Agentbewerkingen controleren: Het identiteitsgebruik van agents vastleggen en bewaken voor beveiliging en naleving.
  6. Test beide patronen: valideer zowel autonome als gedelegeerde scenario's in uw tests.
  7. Documentintentie: documenteer duidelijk welk agentpatroon geschikt is voor elke use-case.

Verwante inhoud

  • Last updated on