Agent2Agent-authenticatie (A2A)

Met het Protocol Agent2Agent (A2A) kunnen uw agents andere agents aanroepen. Voor de meeste A2A-eindpunten is verificatie vereist voor toegang tot het eindpunt en de onderliggende service. Het configureren van verificatie zorgt ervoor dat alleen geautoriseerde gebruikers uw A2A-hulpprogramma's kunnen aanroepen in Foundry Agent Service.

In dit artikel worden de verificatiemethoden uitgelegd die beschikbaar zijn voor A2A-verbindingen en helpt u bij het kiezen van de juiste benadering voor uw scenario.

Verificatiescenario's

Over het algemeen zijn er twee verificatiescenario's:

• Gedeelde verificatie: elke gebruiker van uw agent gebruikt dezelfde identiteit om te verifiëren bij het A2A-eindpunt. Afzonderlijke gebruikerscontext blijft niet behouden. Deze benadering is ideaal wanneer alle gebruikers hetzelfde toegangsniveau moeten hebben. Als u bijvoorbeeld een chatagent bouwt om gegevens op te halen uit Azure Cosmos DB voor uw organisatie, wilt u mogelijk dat elke gebruiker toegang heeft tot dezelfde gedeelde container zonder dat hiervoor afzonderlijke aanmelding is vereist.
• Afzonderlijke verificatie: elke gebruiker van uw agent verifieert zich met zijn eigen account, zodat de gebruikerscontext zich blijft voordoen tijdens interacties. Deze aanpak is essentieel wanneer acties moeten worden afgestemd op de machtigingen van de gebruiker. Als u bijvoorbeeld een coderingsagent bouwt waarmee doorvoer- en pull-aanvragen van GitHub worden opgehaald, moet elke ontwikkelaar zich aanmelden met een eigen GitHub-account, zodat ze alleen opslagplaatsen zien waartoe ze toegang hebben.

Voorwaarden

Voordat u een verificatiemethode kiest, hebt u het volgende nodig:

• Toegang tot de Foundry portal en een project. Zie Projecten maken in Foundry als u er nog geen hebt.
• De rol Azure AI-gebruiker of hoger in uw project. Deze rol verleent machtigingen voor het maken van projectverbindingen en het configureren van agents. Zie op rollen gebaseerd toegangsbeheer in de Foundry-portal voor meer informatie.
• De A2A-eindpunt-URL waarmee u verbinding wilt maken. Neem contact op met de eindpuntuitgever om te bevestigen welke verificatiemethoden het eindpunt ondersteunt.
• Referenties voor de geselecteerde verificatiemethode:
  • Op basis van een sleutel: een API-sleutel, een persoonlijk toegangstoken (PAT) of een ander geheim token van de eindpuntuitgever.
  • Microsoft Entra authenticatie: roltoewijzingen voor de agentidentiteit of projectbeheerde identiteit op de achterliggende service. De specifieke rollen zijn afhankelijk van de service (bijvoorbeeld Cosmos DB Data Reader voor Azure Cosmos DB).

Een verificatiemethode kiezen

De verificatiemethode die u kiest, is afhankelijk van of u gedeelde of afzonderlijke gebruikerscontext nodig hebt en welke verificatieprotocollen het A2A-eindpunt ondersteunt.

Gebruik de volgende tabel om de juiste methode voor uw scenario te kiezen:

Ondersteunde verificatiemethoden

De volgende tabel bevat een overzicht van de verificatiemethoden die beschikbaar zijn voor A2A-verbindingen:

Verificatie op basis van sleutels

Gebruik verificatie op basis van sleutels wanneer het A2A-eindpunt een API-sleutel, een persoonlijk toegangstoken (PAT) of een andere geheime referentie accepteert. Voor een betere beveiliging slaat u gedeelde referenties op in een projectverbinding in plaats van deze tijdens runtime door te geven.

Wanneer u uw A2A-eindpunt verbindt met een agent in de Foundry-portal, maakt Foundry een projectverbinding voor u. Geef de referentienaam (de naam van de HTTP-header) en de referentiewaarde (de headerwaarde) op. De indeling is afhankelijk van wat het eindpunt verwacht.

Algemene referentie-indelingen:

Wanneer de agent het A2A-eindpunt aanroept, haalt Agent Service de referenties op uit de projectverbinding en neemt deze op in de verzoekheaders.

Aanbevolen beveiligingsprocedures voor verificatie op basis van sleutels

• Gebruik referenties met minimale bevoegdheden: vraag alleen de minimale machtigingen aan die nodig zijn voor de taken van de agent.
• Regelmatig tokens draaien: stel een herinnering in om tokens opnieuw te genereren voordat ze verlopen.
• Projecttoegang beperken: beperken wie toegang heeft tot projecten die gedeelde geheimen bevatten.
• Audit referentiegebruik: Bewaak de toegang tot de projectverbinding in uw Azure activiteitenlogboeken.

Microsoft Entra ID authenticatie

Gebruik Microsoft Entra ID verificatie wanneer het A2A-eindpunt en de onderliggende service Microsoft Entra ID tokens accepteren. Met deze methode hoeft u geen geheimen te beheren, omdat Azure het verkrijgen en vernieuwen van tokens automatisch verwerkt.

Agentidentiteit

Gebruik de beheerde identiteit van uw agent om te verifiëren met A2A-eindpunten die ondersteuning bieden voor Microsoft Entra ID verificatie. Wanneer u een agent in agentservice maakt, ontvangt de agent automatisch een beheerde identiteit.

Identiteitslevenscyclus:

• Voordat u publiceert: Alle agents in hetzelfde project delen een gemeenschappelijke identiteit. Dit vereenvoudigt het ontwikkelen en testen.
• Na publicatie: Elke gepubliceerde agent ontvangt een unieke identiteit. Dit biedt isolatie en maakt gedetailleerd toegangsbeheer mogelijk.

Zie Agent identity concepts in Microsoft Foundry voor meer informatie over de levenscyclus van agentidentiteiten.

Verificatie van agent-id's configureren:

1. Identificeer de onderliggende service die het A2A-eindpunt aandrijft (bijvoorbeeld Azure Cosmos DB of Azure Storage).
2. Wijs de vereiste rollen toe aan de agentidentiteit voor die service. De specifieke rollen zijn afhankelijk van de service en de bewerkingen die uw agent moet uitvoeren.
3. Configureer de A2A-verbinding om verificatie van agentidentiteit te gebruiken.

Wanneer de agent het A2A-eindpunt aanroept, gebruikt agentservice de agent-id om een autorisatietoken aan te vragen bij Microsoft Entra ID en deze in de aanvraag op te halen.

Beheerde identiteit van het Foundry-project

Gebruik de beheerde identiteit van uw Foundry-project om te verifiëren met A2A-eindpunten. Deze optie is handig als u wilt dat alle agents in een project dezelfde identiteit delen voor toegang tot resources.

Verificatie van door project beheerde identiteit configureren:

1. Identificeer de onderliggende service waarmee het A2A-eindpunt wordt gebruikt.
2. Wijs de vereiste rollen toe aan de beheerde identiteit van het project voor die service.
3. Configureer de A2A-verbinding voor het gebruik van door project beheerde identiteitverificatie.

Wanneer de agent het A2A-eindpunt aanroept, gebruikt agentservice de beheerde identiteit van het project om een autorisatietoken aan te vragen bij Microsoft Entra ID en deze in de aanvraag op te halen.

Passthrough voor OAuth-identiteit

Met OAuth-identiteitspassthrough kan uw agent namens afzonderlijke gebruikers handelen. Gebruik deze methode wanneer acties moeten worden afgestemd op de machtigingen van elke gebruiker, zoals toegang tot hun persoonlijke bestanden, opslagplaatsen of andere beveiligde resources.

OAuth-identiteitspassthrough werkt met Microsoft- en niet-Microsoft A2A-eindpunten die ondersteuning bieden voor OAuth 2.0, inclusief services die gebruikmaken van Microsoft Entra ID.

Hoe OAuth identity passthrough werkt

1. Eerste interactie: Wanneer een gebruiker voor het eerst met uw agent communiceert, genereert agentservice een toestemmingskoppeling.
2. Gebruikerstoestemming: de gebruiker opent de koppeling, meldt zich aan bij de onderliggende service en geeft de agent toestemming om toegang te krijgen tot hun gegevens.
3. Tokenopslag: agentservice slaat de OAuth-tokens van de gebruiker veilig op (toegangstoken en vernieuwingstoken). Deze tokens zijn gericht op die specifieke combinatie van gebruikers en agents.
4. Volgende aanvragen: Wanneer de agent het A2A-eindpunt aanroept, bevat agentservice het toegangstoken van de gebruiker in de aanvraag. Als het toegangstoken verloopt, gebruikt Agentservice het verversingstoken om een nieuw token te verkrijgen.

OAuth-tokentypen

OAuth maakt gebruik van twee typen tokens:

OAuth-bereiken definiëren wat de agent namens de gebruiker kan openen en doen. De scopes worden opgegeven wanneer u de verbinding configureert en aan de gebruiker worden gepresenteerd tijdens het toestemmingsproces. Zie de Microsoft beveiligingsdocumentatie voor meer informatie over OAuth.

Beheerde OAuth versus aangepaste OAuth

Agent Service ondersteunt twee OAuth-configuratieopties:

Als u aangepaste OAuth wilt configureren, geeft u de volgende informatie op:

• Client-id: de toepassings-id van uw OAuth-app-registratie.
• Clientgeheim (indien nodig): het geheim dat is gekoppeld aan uw app-registratie.
• Autorisatie-URL: het eindpunt waar gebruikers toegang autoriseren.
• Token-URL: het eindpunt waar agentservice de autorisatiecode voor tokens uitwisselt.
• URL vernieuwen: het eindpunt voor het vernieuwen van verlopen toegangstokens.
• Scopes: De machtigingen die uw agent nodig heeft (bijvoorbeeld repo voor GitHub of Files.Read voor Microsoft Graph).

Niet-geverifieerde toegang

Gebruik alleen niet-geverifieerde toegang wanneer het A2A-eindpunt openbaar toegankelijk is en geen verificatie vereist. Deze optie komt zelden voor in productiescenario's, maar is mogelijk geschikt voor:

• Openbare API's waarvoor geen verificatie is vereist
• Interne ontwikkelings- of testeindpunten
• Eindpunten die worden beveiligd door beveiliging op netwerkniveau (zoals privé-eindpunten) in plaats van verificatie

Verificatie instellen voor een A2A-verbinding

Volg deze stappen om verificatie te configureren voor een A2A-verbinding:

1. Identificeer het A2A-eindpunt en ondersteunde verificatiemethoden. Neem contact op met de eindpuntuitgever of raadpleeg de eindpuntdocumentatie om te bepalen welke verificatiemethoden worden ondersteund.

2. Verzamel de vereiste referenties op basis van de gekozen verificatiemethode:

   • Sleutelgebaseerd: haal de API-sleutel of het token op van de eindpuntuitgever.
   • Microsoft Entra ID: identificeer de vereiste roltoewijzingen voor de onderliggende service.
   • OAuth: Bepaal of beheerde OAuth beschikbaar is of verzamel de registratiegegevens van uw aangepaste OAuth-app.

3. Maak een projectverbinding in de Foundry-portal. De verbinding slaat de A2A-eindpunt-URL, verificatiemethode en referenties op.

   • Zie Een nieuwe verbinding met uw project toevoegen voor algemene richtlijnen voor verbindingen.
   • Zie Een A2A-agenteindpunt toevoegen aan Foundry Agent Service voor A2A-specifieke configuratie.

4. Roltoewijzingen configureren (alleen Microsoft Entra ID authenticatie). Wijs de vereiste rollen toe aan de agentidentiteit of de beheerde identiteit van het project op de onderliggende service.

5. Voeg het A2A-hulpprogramma toe aan uw agent. Verwijs naar de projectverbinding die u hebt gemaakt en configureer welke hulpprogramma's van het A2A-eindpunt uw agent kan aanroepen.

Verificatie valideren

Nadat u verificatie hebt geconfigureerd, test u de verbinding om te bevestigen dat deze correct werkt.

Verificatie op basis van sleutels of Microsoft Entra ID valideren

1. Open uw agent in de Foundry-portal.
2. Start een gesprek en activeer een actie die het A2A-hulpprogramma aanroept.
3. Controleer of de aanroep van het hulpprogramma is voltooid. Als de aanroep mislukt, controleert u het foutbericht en raadpleegt u Probleemoplossing.

Het valideren van het passthrough voor OAuth-identiteit

1. Open uw agent in de Foundry-portal met behulp van een testgebruikersaccount dat nog niet eerder toestemming heeft gegeven.
2. Start een gesprek en activeer een actie die het A2A-hulpprogramma aanroept.
3. Controleer of er een toestemmingslink bij het antwoord van de agent wordt weergegeven.
4. Open de toestemmingskoppeling en log in met de inloggegevens van de testgebruiker.
5. Autoriseren van de aangevraagde machtigingen.
6. Ga terug naar de agent en activeer het A2A-hulpprogramma opnieuw.
7. Controleer of de aanroep van het hulpprogramma succesvol is voltooid met behulp van de referenties van de testgebruiker.
8. (Optioneel) Test met een ander gebruikersaccount om te bevestigen dat toestemmingsstromen voor meerdere gebruikers werken.

Probleemoplossing

Gebruik de volgende tabel om veelvoorkomende verificatieproblemen vast te stellen en op te lossen:

Verwante inhoud

• Voeg een A2A-agenteindpunt toe aan de Foundry Agent-service: stapsgewijze handleiding voor het configureren van een A2A-hulpprogramma voor uw agent.
• Agent-identiteitconcepten in Microsoft Foundry: Leer hoe agent-identiteiten werken en wat hun levenscyclus is.
• Toegangsbeheer op basis vanrol voor Microsoft Foundry: Informatie over de rollen en machtigingen die beschikbaar zijn in Foundry.
• Voeg een nieuwe verbinding toe aan uw project: Algemene richtlijnen voor het maken van projectverbindingen.