View a markdown version of this page

Zugriffstoken für Workloads abrufen - Amazon Grundgestein AgentCore
Was ist ein Workload-Zugriffstoken?Wie Runtime und Gateway automatisch Token abrufenWie werden Workload-Zugriffstoken manuell abgerufenSicherheitskontrollen für die GetWorkloadAccessTokenForUserIdAPI

Zugriffstoken für Workloads abrufen

Für die Entwicklung von Secure Agent-Anwendungen ist es wichtig zu verstehen, was Workload-Zugriffstoken sind, wie man sie erhält und welche Sicherheitsaspekte bei der Arbeit mit ihnen bestehen. In diesem Abschnitt werden die wichtigsten Konzepte und Implementierungsmuster behandelt, die Sie kennen müssen.

Was ist ein Workload-Zugriffstoken?

Ein Workload-Zugriffstoken ist ein mit AWS-signiertem, undurchsichtigem Zugriffstoken, das es Agenten ermöglicht, auf AgentCore Dienste von Erstanbietern zuzugreifen, z. B. auf Anbieter für ausgehende Anmeldeinformationen. Runtime stellt Workload-Zugriffstoken automatisch als Payload-Header an die Ausführungsinstanzen der Agenten bereit, sodass in den meisten Szenarien keine manuelle Tokenverwaltung erforderlich ist.

Schlüsselmerkmale

  • First-party nur Dienste — Workload-Zugriffstoken dienen ausschließlich dem Zugriff auf Dienste von AWS Erstanbietern und können nicht für externe AgentCore Dienste verwendet werden

  • Automatische Bereitstellung — Runtime und Gateway stellen diese Token den Agenten während der Ausführung automatisch zur Verfügung

  • Integrierte Sicherheit — Runtime-managed Agentenidentitäten können Workload-Zugriffstoken nicht direkt abrufen, wodurch Token-Extraktion und Missbrauch verhindert werden

  • Bindung von Benutzer- und Agenten-Identitäten — Token enthalten sowohl Benutzeridentitäts- als auch Agenten-Identitätsinformationen für einen sicheren Zugriff auf Anmeldeinformationen

Wie Runtime und Gateway automatisch Token abrufen

Wenn ein Agent über AgentCore Runtime oder Gateway mit eingehender Authentifizierung aufgerufen wird, übernimmt der Dienst automatisch die Generierung von Workload-Zugriffstoken:

  1. Runtime validiert das OAuth-Token (Aussteller, Signatur) des Identitätsanbieters für eingehende Nachrichten

  2. Runtime extrahiert Emittenten- und Unteransprüche aus dem OAuth-Token, das die Benutzeridentität darstellt

  3. Runtime ruft die zugehörige Workload-Identität des Agenten ab

  4. Runtime ruft sowohl GetWorkloadAccessTokenForJWT mit Benutzeridentität als auch mit Agent-Workload-Identität auf

  5. Runtime übergibt das Workload-Zugriffstoken als Teil des Payload-Headers für den Aufruf an den Agentencode

Dieser automatische Prozess stellt sicher, dass Agenten ohne manuelles Eingreifen Tokens mit dem richtigen Gültigkeitsbereich erhalten.

Wie werden Workload-Zugriffstoken manuell abgerufen

Je nachdem, wie Sie den Endbenutzer des Agenten identifizieren können, gibt es zwei Muster, die zum Abrufen des Workload-Zugriffstokens verwendet werden können:

Muster 1: JWT-based Identifizierung (für die Produktion empfohlen)

Wenn der Anrufer des Agenten über ein JWT verfügt, das von einem Identitätsanbieter für den Endbenutzer ausgestellt wurde, fordern Sie mithilfe von. GetWorkloadAccessTokenForJWT Wenn Sie ein JWT angeben, validiert AgentCore Identity das Token, um sicherzustellen, dass es korrekt signiert und nicht abgelaufen ist, und verwendet seine Ansprüche „iss“ und „sub“, um den Benutzer eindeutig zu identifizieren. Anmeldeinformationen, die vom Agenten im Namen des Benutzers gespeichert werden, werden dieser kryptografisch verifizierten Identität zugeordnet, und future Abrufe erfordern ein gültiges Workload-Zugriffstoken mit derselben Identität.

Verwenden Sie dieses Muster in folgenden Fällen:

  • Ihre Anwendung ist in einen Identitätsanbieter integriert (Cognito, Auth0, Okta usw.)

  • Sie benötigen einen kryptografischen Nachweis der Identität des Endbenutzers

  • Sie führen die Bereitstellung in der Produktionsumgebung durch

Muster 2: UserId-based Identifizierung

Wenn der Anrufer des Agenten nicht über ein JWT verfügt, das den Endbenutzer identifiziert, fordern Sie ein Workload-Zugriffstoken GetWorkloadAccessTokenForUserId mit einer eindeutigen Zeichenfolge an, die den Benutzer identifiziert.

Verwenden Sie dieses Muster, wenn:

  • Ihre Anwendung verwaltet ihre eigenen Benutzerkennungen und Sie müssen vom Kunden verwaltete UserID-Zeichenfolgen an Identity übergeben AgentCore

  • Sie befinden sich in einem Entwicklungs- oder Schnellstartszenario, in dem ein IdP-Token noch nicht verfügbar ist

  • Ihre Unternehmensarchitektur löst die Benutzeridentität im Vorfeld auf und übergibt eine vertrauenswürdige Kennung an den Agenten-Workload

Kompromiss: Die Plattform behandelt die userId als undurchsichtige Zeichenfolge und kann sie nicht anhand einer authentifizierten Endbenutzeridentität überprüfen. Die Sicherheitsbindung hängt davon ab, dass der aufrufende Workload die richtige userId übergibt und dass die IAM-Richtlinien entsprechend abgegrenzt werden. Empfohlene Kontrollen finden Sie unter. Sicherheitskontrollen für die GetWorkloadAccessTokenForUserIdAPI

Codebeispiele

Die folgenden Beispiele veranschaulichen die Verwendung des AgentCore SDK zum Abrufen eines Workload-Zugriffstokens mit diesen beiden Methoden:

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

Sicherheitskontrollen für die GetWorkloadAccessTokenForUserIdAPI

Die GetWorkloadAccessTokenForUserId API akzeptiert eine vom Aufrufer bereitgestellte Benutzer-ID-Zeichenfolge und gibt ein Workload-Zugriffstoken aus, das auf dieses User-Agent-Paar beschränkt ist. Diese API wurde entwickelt, um Unternehmenskunden zu unterstützen, die vom Kunden verwaltete UserID-Zeichenfolgen übergeben müssen, und Builder, für die während der Entwicklung keine Identity Provider (IdP) -Token verfügbar sind.

Wichtig

Wenn Sie den Wert verwendenGetWorkloadAccessTokenForUserId, behandelt die Plattform den userId Wert als undurchsichtige Zeichenfolge und überprüft ihn nicht mit einer authentifizierten Endbenutzeridentität. Die Sicherheitsbindung hängt vollständig davon ab, dass der aufrufende Workload die richtige userId weitergibt und dass Ihre IAM-Richtlinien entsprechend abgegrenzt werden. Wenn Ihre Anwendung Zugriff auf ein JWT hat, das den Endbenutzer identifiziert, verwenden Sie GetWorkloadAccessTokenForJWT stattdessen, das den Aussteller, die Signatur und den Ablauf des Tokens überprüft, bevor ein Workload-Zugriffstoken ausgestellt wird.

Die GetWorkloadAccessTokenForUserId API implementiert mehrere Sicherheitskontrollen, um unbefugten Zugriff zu verhindern:

  • Überprüfung der Workload-Identität — Die API überprüft, ob die anfragende Identität berechtigt ist, im Namen der angegebenen Workload-Identität zu handeln

  • Service-managed Identitätseinschränkung — Runtime-managed und Gateway-managed Workload-Identitäten können Token nicht direkt abrufen. Dadurch wird verhindert, dass Agenten Token für missbräuchliche Zwecke extrahieren

  • IAM-Berechtigungsanforderungen — Anrufer müssen über entsprechende IAM-Berechtigungen verfügen, einschließlich, und GetWorkloadAccessToken GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

  • Token-Scoping — Tokens sind auf das spezifische User-Agent-Paar beschränkt, sodass sichergestellt ist, dass auf die Anmeldeinformationen, die unter einem Benutzer gespeichert sind, nicht von einem anderen Benutzer zugegriffen werden kann

  • Benutzer-ID-Partitionierung für mehrere Identitätsanbieter — Wenn Sie mehrere Identitätsanbieter verwenden, partitionieren Sie Ihre Benutzer-IDs anhand des Musters, um Benutzerkollisionen zwischen verschiedenen Anbietern provider_id+user_id zu verhindern. Verwenden Sie beispielsweise cognito+user123 und, auth0+user123 um Benutzer mit derselben Kennung bei verschiedenen Identitätsanbietern zu unterscheiden

Empfohlene Sicherheitskontrollen

Da die Plattform die UserID-Zeichenfolge nicht überprüfen kann, sind Sie dafür verantwortlich, die Integrität des an diese API übergebenen Werts sicherzustellen. Wenden Sie die folgenden Steuerelemente an:

  • Bevorzugen SieGetWorkloadAccessTokenForJWT, wenn ein JWT verfügbar ist — Der JWT-based Pfad validiert den Aussteller und die Signatur des Tokens und liefert so einen kryptografischen Nachweis für die Identität des Benutzers. GetWorkloadAccessTokenForUserIdNur verwenden, wenn ein JWT nicht verfügbar ist.

  • Die userId aus einer vertrauenswürdigen Quelle ableiten — Der UserID-Wert sollte aus dem Kontext des authentifizierten Prinzipals abgeleitet werden (z. B. IAM-Aufruferidentität, Sitzungsattribute oder eine Upstream-Identitätsauflösungsschicht), anstatt beliebige vom Client bereitgestellte Werte zu akzeptieren. Dadurch wird verhindert, dass sich ein authentifizierter Anrufer als ein anderer Benutzer ausgibt.

  • Beschränken Sie die IAM-Berechtigung — Nur vertrauenswürdige Principals sollten über diese Berechtigung verfügen. bedrock-agentcore:GetWorkloadAccessTokenForUserId Schränken Sie diese Berechtigung auf bestimmte Workload-Identitätsressourcen ein. Erteilen Sie sie nicht pauschal über verwaltete Richtlinien oder Platzhalter-Ressourcenangaben.

  • VerweigernGetWorkloadAccessTokenForUserId, wo sie nicht benötigt wird — Für Workloads, für die immer ein JWT verfügbar ist, lehnen Sie die Aktion in den IAM-Richtlinien explizit ab, um zu verhindern, dass der Benutzer-ID-Pfad verwendet wird:

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • Auditprotokollierung implementieren — Protokollieren Sie die Beziehung zwischen dem authentifizierten IAM-Prinzipal und dem übergebenen UserID-Wert. Wird verwendet AWS CloudTrail , um GetWorkloadAccessTokenForUserId Anrufe zu überwachen und unerwartete UserID-Werte zu erkennen.

Wenn der Fehler "WorkloadIdentity ist mit einem Dienst verknüpft und kann vom Aufrufer kein Zugriffstoken abgerufen werden“ auftritt, bedeutet dies, dass die Workload-Identität von Runtime oder Gateway verwaltet wird und Token nicht direkt abgerufen werden können. Diese Einschränkung trägt zur Einhaltung der Sicherheitsgrenzen bei und verhindert unbefugten Tokenzugriff.

Für zusätzliche Sicherheitskontrollen können Sie detaillierte Zugriffsrichtlinien implementieren, um einzuschränken, welche Workload-Identitäten auf bestimmte Anmeldeinformationsanbieter zugreifen können. Weitere Informationen finden Sie unter Eingrenzung des Zugriffs auf Anmeldeinformationsanbieter anhand der Workload-Identität.