# Authentifizieren und autorisieren Sie mit Inbound Auth und Outbound Auth
[In diesem Abschnitt erfahren Sie, wie Sie die Authentifizierung und Autorisierung für Ihre Agentenlaufzeit mithilfe von OAuth- und JWT-Trägertoken mit Identity implementieren. AgentCore ](identity.md) Sie erfahren, wie Sie Cognito-Benutzerpools einrichten, Ihre Agentenlaufzeit für die JWT-Authentifizierung (Inbound Auth) konfigurieren und den OAuth-based Zugriff auf Ressourcen von Drittanbietern (Outbound Auth) implementieren.
Ein vollständiges Beispiel finden Sie unter. [https://github.com/awslabs/amazon-bedrock-agentcore-samples/](https://github.com/awslabs/amazon-bedrock-agentcore-samples/)
Informationen zur Verwendung von OAuth mit einem MCP-Server finden Sie unter [Bereitstellen von MCP-Servern](runtime-mcp.md) in Runtime. AgentCore
Amazon Bedrock AgentCore Runtime bietet zwei Authentifizierungsmechanismen für gehostete Agenten:
**IAM-SigV4-Authentifizierung**
Der standardmäßige Authentifizierungs- und Autorisierungsmechanismus, der automatisch ohne zusätzliche Konfiguration funktioniert, ähnlich wie andere AWS APIs.
**X-Amzn-Bedrock-AgentCore-Runtime-User-Id Kopfzeile**
Wenn Ihre Lösung erfordert, dass der gehostete Agent OAuth-Token im Namen von Endbenutzern abruft (mithilfe von Authorization Code Grant), können Sie die Benutzer-ID angeben, indem Sie den `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` Header in Ihre Anfragen aufnehmen. Dieser Header verwendet den `GetWorkloadAccessTokenForUserId` Pfad intern.
Für den `X-Amzn-Bedrock-AgentCore-Runtime-User-Id header` Aufruf InvokeAgentRuntime mit ist zusätzlich zur vorhandenen `bedrock-agentcore:InvokeAgentRuntime` Aktion eine neue IAM-Aktion: `bedrock-agentcore:InvokeAgentRuntimeForUser` erforderlich.
**Wann sollte dieser Header im Vergleich zur JWT Bearer Token Authentifizierung verwendet werden**
Dieser Header ist für die folgenden Anwendungsfälle konzipiert:
+ **Unternehmenskunden mit kundenverwalteten Benutzerkennungen** — Organizations, die ihre eigenen Benutzeridentitätszeichenfolgen verwalten und diese zur Bindung von Anmeldeinformationen an AgentCore Identity weitergeben müssen.
+ **Entwicklungs- und Schnellstartszenarien** — Entwickler, die noch kein IdP-Token zur Verfügung haben und einen schnellen Weg benötigen, um benutzerspezifische Anmeldedatenflüsse zu testen.
[Verwenden Sie für Produktionsbereitstellungen, in denen Sie einen Identitätsanbieter konfiguriert haben, stattdessen die JWT Bearer Token Authentifizierung.](#oauth-sample-overview) Der JWT-Pfad (`GetWorkloadAccessTokenForJWT`) validiert den Aussteller, die Signatur und den Ablauf des Tokens und liefert so einen kryptografischen Nachweis für die Identität des Benutzers. Der `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` Header-Pfad überprüft die userId nicht mit einer authentifizierten Endbenutzeridentität. Er ist darauf angewiesen, dass der aufrufende Workload den richtigen Wert weitergibt, und dass Ihre IAM-Richtlinien einschränken, wer ihn bereitstellen kann.
**Bewährte Sicherheitsmethoden für Header X-Amzn-Bedrock-AgentCore-Runtime-User-Id **
**Tipp**
Eine konsolidierte Übersicht aller Runtime-Sicherheitsempfehlungen finden Sie unter [Bewährte Sicherheitsmethoden für AgentCore Runtime](runtime-security-best-practices.md).
Da der Header-Wert als undurchsichtigen Bezeichner AgentCore behandelt wird, ohne ihn mit einer authentifizierten Identität zu vergleichen, müssen Sie die folgenden Kontrollen anwenden, um die Sicherheitsgrenze aufrechtzuerhalten:
+ **Beschränken Sie die IAM-Berechtigung** — Nur vertrauenswürdige Principals sollten über diese Berechtigung verfügen. `bedrock-agentcore:InvokeAgentRuntimeForUser` Weisen Sie diese Berechtigung mithilfe von IAM-Ressourcenbedingungen auf bestimmte Laufzeitressourcen zu. Erteilen Sie sie nicht allgemein über verwaltete Richtlinien oder Platzhalter-Ressourcenanweisungen.
+ **Benutzer-ID vom authentifizierten Prinzipal ableiten — Der** Benutzer-ID-Wert sollte aus dem Kontext des authentifizierten Prinzipals abgeleitet werden (z. B. IAM-Anruferidentität oder Benutzertoken-Ansprüche), anstatt beliebige vom Client bereitgestellte Werte zu akzeptieren. Dadurch wird verhindert, dass sich ein authentifizierter Benutzer als ein anderer Benutzer ausgibt, indem er manuell einen anderen Benutzer angibt. `user-id`
+ **Implementieren Sie die Auditprotokollierung — Protokollieren** Sie die Beziehung zwischen dem authentifizierten IAM-Prinzipal (aus dem SigV4-Kontext) und dem übergebenen Wert. `user-id` Wird verwendet AWS CloudTrail , um `InvokeAgentRuntime` Aufrufe zu überwachen, die den Parameter enthalten. `runtimeUserId`
+ **Den Header in nicht vertrauenswürdigen Kontexten ablehnen** — Für Laufzeiten, in denen keine Benutzer-ID-Delegierung erforderlich ist, sollten Sie die `bedrock-agentcore:InvokeAgentRuntimeForUser` Aktion in den IAM-Richtlinien explizit ablehnen, um zu verhindern, dass der Header akzeptiert wird:
```
{
"Statement": [
{
"Sid": "DenyUserIdDelegation",
"Effect": "Deny",
"Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
"Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
}
]
}
```
**Authentifizierung mit JWT-Trägertoken**
Sie können Ihre Agenten-Laufzeit so konfigurieren, dass sie JWT-Bearer-Token akzeptiert, indem Sie bei der Agentenerstellung die Autorisierungskonfiguration angeben.
Diese Konfiguration umfasst:
+ Discovery-URL — Eine Zeichenfolge, die dem Muster `^.+/\.well-known/openid-configuration$` für OpenID Connect-Discovery-URLs entsprechen muss
+ Zulässige Zielgruppen — Eine Liste der zulässigen Zielgruppen, die anhand des Aud-Antrags im JWT-Token validiert wird
+ Zulässige Clients — Eine Liste zulässiger Client-IDs, die anhand des client\_id-Anspruchs im JWT-Token validiert werden
+ Zulässige Bereiche — Eine Liste der zulässigen Bereiche, die anhand des Bereichsanspruchs im JWT-Token validiert wird. Das `allowedScopes` Autorisierungsfeld wird als eine Liste von Zeichenketten konfiguriert.
+ Erforderliche benutzerdefinierte Ansprüche — Eine Liste der erforderlichen Ansprüche, die anhand des Namens und Werts des Antrags, der im eingehenden JWT-Token enthalten ist, überprüft wird. Einzelheiten zur Konfiguration des Autorisierers finden Sie unter Konfiguration des [eingehenden](inbound-jwt-authorizer.md) JWT-Autorisierers
**Anmerkung**
Eine AgentCore Runtime kann entweder auf IAM SigV4 oder auf JWT Bearer Token basierende eingehende Authentifizierung unterstützen, jedoch nicht beide gleichzeitig. Sie können jederzeit verschiedene Versionen Ihrer AgentCore Runtime erstellen und diese für unterschiedliche Autorisierungstypen für eingehende Anfragen konfigurieren. Wenn Sie eine Laufzeit mit Amazon Bedrock erstellen AgentCore, wird automatisch eine Workload Identity für Ihre Laufzeit mit AgentCore Identity Service erstellt.
**Topics**
+ [Beschränken Sie den eingehenden IAM-Aufruf (SigV4) auf Ihr Gateway](#runtime-restrict-iam-gateway)
+ [Beispiel für eingehende JWT-Autorisierung und ausgehenden OAuth-Zugriff](#oauth-sample-overview)
+ [Voraussetzungen](#oauth-prerequisites)
+ [Schritt 1: Erstellen Sie Ihr Agentenprojekt](#prepare-agent)
+ [Schritt 2: Einrichten AWS Cognito-Benutzerpool und Benutzer hinzufügen](#setup-cognito)
+ [Schritt 3 (optional): Stellen Sie Ihre Laufzeit mit einem AgentCore Gateway vor](#runtime-front-with-gateway)
+ [Schritt 4: Stellen Sie Ihren Agenten bereit](#deploy-agent)
+ [Schritt 5: Verwenden Sie das Bearer-Token, um Ihren Agenten aufzurufen](#oauth-invoke-agent)
+ [OAuth-Fehlerantworten](#oauth-error-responses)
+ [Schritt 6: Richten Sie Ihren Agenten für den Zugriff auf Tools mithilfe von OAuth ein](#oauth-outbound-access)
+ [Schritt 7: (Optional) Propagieren Sie ein JWT-Token an Runtime AgentCore](#oauth-propagate-jwt-token)
+ [Fehlerbehebung](#troubleshooting)
## Beschränken Sie den eingehenden IAM-Aufruf (SigV4) auf Ihr Gateway
Sie können Ihre AgentCore Runtime mit einem AgentCore Gateway versehen, sodass das Gateway zum einzigen, kontrollierten Einstiegspunkt zur Runtime wird. So erhalten Sie richtlinienbasierte Autorisierung, Amazon Bedrock Guardrails, Request and Response Interceptors und einheitliche Observability, die alle außerhalb der eigenen Umgebung des Agenten angewendet werden. [Die vollständige Begründung und die Einrichtung finden Sie unter Fronten Sie Ihre Runtime mit einem Gateway. AgentCore ](runtime-security-best-practices.md#security-bp-front-with-gateway)
Dies ist jedoch nur sinnvoll, wenn Anrufer die Runtime nicht direkt unter Umgehung des Gateways erreichen können. Wenn Ihre Runtime die standardmäßige eingehende IAM-Autorisierung (SigV4) verwendet, können Sie den Aufruf auf das Gateway beschränken, sodass der Datenverkehr die Laufzeit nur über das Gateway erreicht. Um dies zu erreichen, fügen Sie der Runtime eine ressourcenbasierte Richtlinie hinzu, die den Aufruf auf die Ausführungsrolle Ihres Gateways beschränkt. Das Gateway übernimmt seine Dienstrolle beim Signieren von Anfragen an die Laufzeit, sodass die Gateway-Rolle der Principal ist, der die Laufzeit aufruft. Erlauben Sie diese Rolle und fügen Sie `Deny` für jeden anderen Prinzipal eine explizite Rolle hinzu, sodass keine andere Identität die Laufzeit aufrufen kann, auch nicht mit einer permissiven identitätsbasierten Richtlinie. Weitere Informationen zu ressourcenbasierten Richtlinien für Laufzeiten finden Sie unter [Resource-based Richtlinien für](resource-based-policies.md) Amazon Bedrock. AgentCore
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowOnlyGatewayRole",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
},
{
"Sid": "DenyOtherPrincipals",
"Effect": "Deny",
"Principal": { "AWS": "*" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
"Condition": {
"ArnNotEquals": {
"aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
}
}
}
]
}
```
**Tipp**
Eine explizite Angabe `Deny` hat immer Vorrang vor allen Richtlinien`Allow`, auch denen, die auf Identität basieren, für dasselbe Konto. Durch die Eingabe von `Deny` On `aws:PrincipalArn` wird sichergestellt, dass nur die Ausführungsrolle Ihres Gateways die Laufzeit aufrufen kann, unabhängig davon, welche anderen Berechtigungen in Ihrem Konto vorhanden sind.
**Wichtig**
Die Beschränkung der Laufzeit auf die Ausführungsrolle des Gateways ist nur so wirksam wie die Kontrolle darüber, wer diese Rolle übernehmen kann. Jeder Principal, der die Gateway-Ausführungsrolle übernehmen kann, kann die Laufzeit aufrufen, als wäre es das Gateway. Sperren Sie die Rolle, indem Sie `aws:SourceArn` der Vertrauensrichtlinie der **Gateway-Ausführungsrolle `aws:SourceAccount`** Bedingungen hinzufügen, sodass nur Ihr Gateway sie übernehmen kann. Die Anleitung [zur Verhinderung von Confused Deputy](runtime-security-best-practices.md#security-bp-confused-deputy) zeigt, dass dieselbe Technik auf die Ausführungsrolle einer Laufzeit angewendet wird. Wenden Sie hier dasselbe Muster an, legen Sie jedoch die Vertrauensrichtlinie für die Gateway-Ausführungsrolle und den Geltungsbereich `aws:SourceArn` auf Ihren Gateway-ARN fest.
## Beispiel für eingehende JWT-Autorisierung und ausgehenden OAuth-Zugriff
In diesem Handbuch erfahren Sie, wie Sie Ihre Agenten-Laufzeit so einrichten, dass sie mit einem OAuth-kompatiblen Zugriffstoken im JWT-Format aufgerufen wird. Der Probenagent wird mithilfe von AWS Cognito-Zugriffstoken autorisiert. Später erfahren Sie auch, wie der Agentencode Google-Token im Namen des Nutzers abrufen kann, um Google Drive zu überprüfen und Inhalte abzurufen.
**Was du lernen wirst**
In diesem Leitfaden erfahren Sie, wie Sie:
+ Richten Sie den Cognito-Benutzerpool ein, fügen Sie einen Benutzer hinzu und rufen Sie ein Bearer-Token für den Benutzer ab
+ Richten Sie Ihre Agenten-Laufzeit so ein, dass sie den Cognito-Benutzerpool für die Autorisierung verwendet
+ Richten Sie Ihren Agentencode so ein, dass OAuth-Token im Namen des Benutzers abgerufen werden, um Tools aufzurufen
## Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:
+ Ein AWS Konto mit den entsprechenden Berechtigungen
+ Grundlegendes Verständnis der Python-Programmierung
+ Vertrautheit mit Docker-Containern (für fortgeschrittene Bereitstellung)
+ Richten Sie erfolgreich einen Basisagenten mit Runtime ein
+ Die neueste AWS CLI und `jq` installiert
+ Grundlegendes Verständnis der OAuth-Autorisierung, hauptsächlich JWT-Bearer-Token, Claims und der verschiedenen Zuschussflüsse
## Schritt 1: Erstellen Sie Ihr Agentenprojekt
Verwenden Sie den `agentcore create` Befehl, um ein Skeleton-Agent-Projekt mit dem Framework Ihrer Wahl einzurichten:
```
agentcore create
```
Der Befehl fordert Sie auf zu:
+ Wählen Sie ein Framework (wählen Sie Strands Agents für dieses Tutorial)
+ Geben Sie einen Projektnamen an
+ Zusätzliche Optionen konfigurieren
Folgendes wird generiert:
+ Agentencode mit dem von Ihnen ausgewählten Framework
+ `agentcore/agentcore.json` Konfigurationsdatei
+ `requirements.txt`mit den notwendigen Abhängigkeiten
**Anmerkung**
Der generierte Agentencode dient als Grundlage für die Implementierung der OAuth-Authentifizierung in den folgenden Schritten.
## Schritt 2: Einrichten AWS Cognito-Benutzerpool und Benutzer hinzufügen
Um einen Cognito-Benutzerpool einzurichten und einen Benutzer zu erstellen, verwenden Sie ein Shell-Skript, das den Vorgang automatisiert.
Weitere Informationen finden Sie unter [Schritt 2: Identitäts- und Authentifizierungsmodule importieren](identity-getting-started-google.md#identity-getting-started-step2).
**So richten Sie den Cognito-Benutzerpool ein und erstellen einen Benutzer**
+ Erstellen Sie eine Datei mit dem Namen `setup_cognito.sh` und dem folgenden Inhalt:
```
#!/bin/bash
# Create User Pool and capture Pool ID directly
export POOL_ID=$(aws cognito-idp create-user-pool \
--pool-name "MyUserPool" \
--policies '{"PasswordPolicy":{"MinimumLength":8}}' \
--region $REGION | jq -r '.UserPool.Id')
# Create App Client and capture Client ID directly
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
--user-pool-id $POOL_ID \
--client-name "MyClient" \
--no-generate-secret \
--explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
--region $REGION | jq -r '.UserPoolClient.ClientId')
# Create User
aws cognito-idp admin-create-user \
--user-pool-id $POOL_ID \
--username $USERNAME \
--region $REGION \
--message-action SUPPRESS > /dev/null
# Set Permanent Password
aws cognito-idp admin-set-user-password \
--user-pool-id $POOL_ID \
--username $USERNAME \
--password $PASSWORD \
--region $REGION \
--permanent > /dev/null
# Authenticate User and capture Access Token
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
--region $REGION | jq -r '.AuthenticationResult.AccessToken')
# Output the required values
echo "Pool id: $POOL_ID"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
echo "Bearer Token: $BEARER_TOKEN"
```
Öffnen Sie ein Terminalfenster und legen Sie die folgenden Umgebungsvariablen fest:
+ {{REGION}}— die AWS Region, die Sie verwenden möchten
+ {{USERNAME}}— der Benutzername für den neuen Benutzer
+ {{PASSWORD}}— das Passwort für den neuen Benutzer
```
export REGION=us-east-1 // set your desired Region
export USERNAME=USER NAME
export PASSWORD=PASSWORD
```
Führen Sie im Terminalfenster das Skript aus:
```
source setup_cognito.sh
```
Notieren Sie sich die Ausgabe des Skripts. Sie benötigen diese Werte in den nächsten Schritten.
Dieses Skript erstellt einen Cognito-Benutzerpool, einen Benutzerpool-Client, fügt einen Benutzer hinzu und generiert ein Bearer-Token für den Benutzer. Das Token ist standardmäßig 60 Minuten gültig.
## Schritt 3 (optional): Stellen Sie Ihre Laufzeit mit einem AgentCore Gateway vor
Sie können Ihre AgentCore Runtime mit einem AgentCore Gateway versehen, sodass das Gateway zum einzigen, kontrollierten Einstiegspunkt zur Runtime wird. So erhalten Sie richtlinienbasierte Autorisierung, Amazon Bedrock Guardrails, Request and Response Interceptors und einheitliche Observability, die alle außerhalb der eigenen Umgebung des Agenten angewendet werden. [Die vollständige Begründung und die Einrichtung finden Sie unter Fronten Sie Ihre Runtime mit einem Gateway. AgentCore ](runtime-security-best-practices.md#security-bp-front-with-gateway)
Wenn Sie diese Runtime bereitstellen möchten, [erstellen Sie jetzt das Gateway](gateway-create.md), bevor Sie die Runtime im nächsten Schritt bereitstellen. Nach der Bereitstellung [fügen Sie die Runtime als Gateway-Ziel](gateway-target-http-runtime.md) hinzu.
Um sicherzustellen, dass Anrufer das Gateway nicht umgehen können, beschränken Sie die Laufzeit so, dass sie nur Aufrufe von diesem Gateway akzeptiert. Sie konfigurieren dies im nächsten Schritt als Teil des Autorisierers mithilfe von `allowedWorkloadConfiguration` (siehe [erlaubtWorkloadConfiguration: Beschränken Sie den Aufruf auf](#deploy-agent-allowed-workload) Ihr Gateway).
## Schritt 4: Stellen Sie Ihren Agenten bereit
**Wichtig**
Ab dem **13. Oktober 2025** AgentCore verwendet Amazon Bedrock eine Service-Linked Rolle (SLR) für Workload-Identitätsberechtigungen, anstatt eine manuelle IAM-Richtlinienkonfiguration für neue Agenten zu erfordern.
Die Service-Linked Rollendetails:
**Name (Name:** `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`
**Leiter des Dienstes:** `runtime-identity.bedrock-agentcore.amazonaws.com`
**Zweck:** Verwaltet Zugriffstoken und OAuth-Anmeldeinformationen für Workloads
Stellen Sie sicher, dass die Rolle, die Sie zum Aufrufen von AgentCore Control-APIs verwenden, berechtigt ist, die Rolle zu erstellen: Service-Linked
```
{
"Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
}
}
}
```
**Vorteil**: Die Service-Linked Rolle stellt automatisch die erforderlichen Berechtigungen für den Zugriff auf Workload-Identitäten bereit, ohne dass eine manuelle Richtlinienkonfiguration erforderlich ist.
Ausführliche Informationen zur Rolle, die mit dem Dienst verknüpft ist, finden Sie unter Rolle, die mit dem [Identitätsdienst verknüpft](service-linked-roles.md#identity-service-linked-role) ist.
Jetzt stellen Sie Ihren Agenten mit JWT-Autorisierung mithilfe des von Ihnen erstellten Cognito-Benutzerpools bereit. Sie müssen einen Agenten mit Authorizer-Konfiguration erstellen. Die folgende Tabelle zeigt die verschiedenen Konfigurationsparameter des Autorisierers und wie wir sie zur Validierung des eingehenden Tokens verwenden.
| authorizer\_configuration | Anspruch im dekodierten Token | Hinweise |
| --- | --- | --- |
| Entdeckungs-URL → Emittent | Miss | Die Discovery-URL sollte auf eine Aussteller-URL verweisen. Dies sollte mit dem ISS-Anspruch im dekodierten Token übereinstimmen. |
| Zulässige Kunden | Client-ID | Die client\_id im Token sollte mit einem der im Authorizer angegebenen zulässigen Clients übereinstimmen |
| Zulässige Zielgruppe | aud | Einer der Werte in aud claim aus dem Token sollte einem der im Autorisierer angegebenen zulässigen Zielgruppen entsprechen |
| erlaubt WorkloadConfiguration | `internal` | Optional. Wird beim Start verwendet, damit nur Ihr AgentCore Gateway die Laufzeit aufrufen kann. Siehe [Beschränken Sie den Aufruf auf Ihr Gateway](#deploy-agent-allowed-workload). |
Wenn sowohl client\_id als auch aud angegeben werden, überprüft der Runtime Authorizer des Agenten beide.
### erlaubtWorkloadConfiguration: Beschränken Sie den Aufruf auf Ihr Gateway
Das `allowedWorkloadConfiguration` Feld auf der `customJWTAuthorizer` schränkt ein, welche Workloads in der Identitätskette der Anfrage die Laufzeit aufrufen dürfen. Stellen Sie die zulässige Arbeitslast auf Ihr Gateway ein, sodass die Runtime eine Anfrage nur akzeptiert, wenn ihre Identitätskette dieses Gateway einschließt. Auf diese Weise erzwingt eine OAuth-Laufzeit (JWT), dass der Datenverkehr nur über das Gateway ankommt, das Sie in Schritt 3 eingerichtet haben.
Sie geben die zulässigen Workloads mithilfe eines der folgenden Felder an. Sie können eines oder beide angeben — eine Anfrage wird akzeptiert, wenn ihre Identitätskette mit einem Eintrag in einem der **beiden** Felder übereinstimmt, sodass Sie nicht beide angeben müssen.
+ **HostingEnvironments** — Eine Liste von Hosting-Umgebungen, deren Workloads das Ziel aufrufen dürfen. Jeder Eintrag ist ein Objekt mit einem. `arn` Beim Start ist AgentCore Gateway die einzige unterstützte Hosting-Umgebung, daher `arn` muss es sich bei jeder Umgebung um einen AgentCore Gateway-ARN ARN.
+ **WorkloadIdentities** — Eine Liste von Workload-Identitätsnamen, die das Ziel aufrufen dürfen. Ein Workload-Identitätsname ist **kein** ARN. Es ist das letzte Segment der Workload-Identität ARN des Gateways, das Sie im `workloadIdentityDetails` Feld der `GetGateway` Antwort finden. Wenn dies beispielsweise der Fall `workloadIdentityDetails.workloadIdentityArn` ist`arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity`, dann lautet der Name der Workload-Identität`my-gateway-workload-identity`.
Im folgenden Beispiel wird eine Agentenlaufzeit erstellt, die den Aufruf auf ein bestimmtes AgentCore Gateway anhand seines ARN beschränkt. Die Angabe `hostingEnvironments` allein ist die einfachste Methode, ein Gateway zuzulassen:
```
{
"authorizerConfiguration": {
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
"allowedClients": ["your-client-id"],
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
}
]
}
}
}
}
```
Alternativ können Sie das Gateway anhand seines Workload-Identitätsnamens identifizieren oder beide Felder angeben. Wenn beide vorhanden sind, ist eine Anfrage zulässig, wenn sie mit einem Eintrag in einem der Felder übereinstimmt. Das folgende `allowedWorkloadConfiguration` Snippet ermöglicht zwei verschiedene Gateways — eines, das durch seinen ARN und eines durch seinen Workload-Identitätsnamen identifiziert wird:
```
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
}
],
"workloadIdentities": [
"my-gateway-2-workload-identity"
]
}
```
**Anmerkung**
Wird beim Start nur für AgentCore Runtime-Ziele unterstützt, und die zulässigen Workloads sind Gateways. `allowedWorkloadConfiguration` AgentCore
### Erstellen und implementieren Sie die Agent-Runtime
Sobald Ihre Authorizer-Konfiguration fertig ist, können Sie die Agent-Runtime erstellen und bereitstellen. Die folgenden Beispiele zeigen, wie Sie dies mit der AgentCore CLI oder dem AWS SDK for Python (Boto3) tun können. Notieren Sie sich den Runtime-ARN des Agenten aus der Ausgabe — Sie benötigen ihn, um den Agenten im nächsten Schritt aufzurufen.
**Example**
**Um Ihren Agenten zu konfigurieren und bereitzustellen**
1. Erstellen Sie Ihr Agentenprojekt mit der AgentCore CLI:
```
agentcore create
```
Wenn Sie dazu aufgefordert werden, wählen Sie Ihr Framework aus (wählen Sie Strands Agents für dieses Tutorial).
1. Stellen Sie Ihren Agenten bereit:
```
agentcore deploy
```
1. Notieren Sie sich den Runtime-ARN des Agenten aus der Ausgabe. Sie benötigen dies im nächsten Schritt.
**Tipp**
Sie können den `agentcore create` Befehl auch ohne Flags ausführen, um ein vollständig interaktives Erlebnis zu erhalten, das Sie durch die Projekteinrichtung führt.
1.
```
import boto3
# Create the client
client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")
# Call the CreateAgentRuntime operation
response = client.create_agent_runtime(
agentRuntimeName='HelloAgent',
agentRuntimeArtifact={
'containerConfiguration': {
'containerUri': '111122223333.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
}
},
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": 'COGNITO_DISCOVERY_URL',
"allowedClients": ['COGNITO_CLIENT_ID']
}
},
networkConfiguration={"networkMode":"PUBLIC"},
roleArn='arn:aws:iam::111122223333:role/AgentRuntimeRole',
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
```
## Schritt 5: Verwenden Sie das Bearer-Token, um Ihren Agenten aufzurufen
Nachdem Ihr Agent nun mit der JWT-Autorisierung bereitgestellt wurde, können Sie ihn mit dem Bearer-Token aufrufen.
**Anmerkung**
Wenn Sie Ihrer Runtime in [Schritt 3](#runtime-front-with-gateway) ein Gateway zugewiesen haben, fügen Sie vor dem Aufruf die bereitgestellte Runtime als Gateway-Ziel hinzu — siehe [AgentCore Runtime-Ziele](gateway-target-http-runtime.md) — und rufen Sie dann über den Gateway-Endpunkt auf, der in den folgenden Beispielen gezeigt wird, und nicht über den Runtime-Endpunkt.
**Wichtig**
**Wichtig für bestehende Benutzer**: Agenten, die **vor dem 13. Oktober 2025 erstellt wurden,** verwenden weiterhin die Rolle „Agentenausführung“ für Identitätsberechtigungen und **erfordern, dass** die oben genannte Richtlinie an die Ausführungsrolle des Agenten angehängt wird.
**Neue Agenten**: Für Agenten**, die am oder nach dem 13. Oktober 2025** erstellt wurden, ist diese Richtlinie **nicht erforderlich**, da die Berechtigungen automatisch von der Service-Linked Rolle verwaltet werden.
```
{
"Sid": "GetAgentAccessToken",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId"
],
# point to the workload identity for the runtime; the workload identity can be found in
# the GetAgentRuntime response and has your agent name in it.
"Resource": [
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
]
}
```
**Rufen Sie den Agenten auf**
Rufen Sie ein Trägertoken für den Benutzer ab, den Sie mit Amazon Cognito erstellt haben.
```
# use the password and other details used when you created the cognito user
export TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
--region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
```
Fahren Sie mit den restlichen Anweisungen fort, um den Agenten aufzurufen.
Rufen Sie den Agenten mit OAuth auf.
**Example**
1.
```
// Invoke with OAuth token
export PAYLOAD='{"prompt": "hello what is 1+1?"}'
export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com"
# If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL
# export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}"
export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT"
# If you fronted the runtime with a gateway (Step 3), the preceding URL works but there is also a simpler alternative:
# export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations"
curl -v -X POST "${INVOKE_URL}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "X-Amzn-Trace-Id: your-trace-id" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: your-session-id" \
-d ${PAYLOAD}
```
1. Da boto3 den Aufruf mit Bearer-Token nicht unterstützt, müssen Sie einen HTTP-Client wie die Requests-Bibliothek in Python verwenden.
**Um Ihren Agenten mit einem Bearer-Token aufzurufen**
1. Erstellen Sie ein Python-Skript `invoke_agent.py` mit dem folgenden Inhalt:
```
import requests
import urllib.parse
import json
import os
# Configuration Constants
REGION_NAME = "AWS_REGION"
# === Agent Invocation Demo ===
invoke_agent_arn = "YOUR_AGENT_ARN_HERE"
auth_token = os.environ.get('TOKEN')
print(f"Using Agent ARN from environment: {invoke_agent_arn}")
# URL encode the agent ARN
escaped_agent_arn = urllib.parse.quote(invoke_agent_arn, safe='')
# Construct the URL — invoke the runtime directly
url = f"https://bedrock-agentcore.{REGION_NAME}.amazonaws.com/runtimes/{escaped_agent_arn}/invocations?qualifier=DEFAULT"
# If you are fronting the runtime with a gateway (see Step 3), invoke through
# the gateway target instead (replace GATEWAY_ID and my-target):
# url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations"
# Set up headers
headers = {
"Authorization": f"Bearer {auth_token}",
"X-Amzn-Trace-Id": "your-trace-id",
"Content-Type": "application/json",
"X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "testsession123"
}
# Enable verbose logging for requests
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)
invoke_response = requests.post(
url,
headers=headers,
data=json.dumps({"prompt": "Hello what is 1+1?"})
)
# Print response in a safe manner
print(f"Status Code: {invoke_response.status_code}")
print(f"Response Headers: {dict(invoke_response.headers)}")
# Handle response based on status code
if invoke_response.status_code == 200:
response_data = invoke_response.json()
print("Response JSON:")
print(json.dumps(response_data, indent=2))
elif invoke_response.status_code >= 400:
print(f"Error Response ({invoke_response.status_code}):")
error_data = invoke_response.json()
print(json.dumps(error_data, indent=2))
else:
print(f"Unexpected status code: {invoke_response.status_code}")
print("Response text:")
print(invoke_response.text[:500])
```
1. {{AWS\_REGION}}Ersetzen Sie es durch die AWS Region, die Sie verwenden. aus Schritt 3.
1. {{YOUR\_AGENT\_ARN\_HERE}}Ersetzen Sie es durch Ihren tatsächlichen Agent-Runtime-ARN aus Schritt 3.
1. Führen Sie das Skript aus:
```
python invoke_agent.py
```
## OAuth-Fehlerantworten
OAuth-configured Agenten folgen den [Authentifizierungsstandards RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) zurück, sodass Clients die Endpunkte des Autorisierungsservers über die API ermitteln können. GetRuntimeProtectedResourceMetadata
### 401 Nicht autorisiert — Fehlende Authentifizierung
Wenn im Authorization-Header kein Bearer-Token angegeben ist, lautet die Antwort:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
Die `resource_metadata` URL im WWW-Authenticate Header verweist auf die PRM-API (Protected Resource Metadata). Mit der PRM-API können Clients herausfinden, welche Autorisierungsserver diesen Agenten und ihre OAuth-Endpunkt-URLs schützen.
**Anmerkung**
Sie müssen Ihren OAuth-Client in Cognito (über AWS Konsole oder CLI) vorab registrieren, um eine zu erhalten, `client_id` bevor Sie die erkannten Endpunkte verwenden können. Amazon Cognito unterstützt keine dynamische Client-Registrierung (RFC 7591).
## Schritt 6: Richten Sie Ihren Agenten für den Zugriff auf Tools mithilfe von OAuth ein
In diesem Abschnitt erfahren Sie, wie Sie Ihren Agentencode mit AgentCore Credential Providern verbinden, um mithilfe der OAuth2-Authentifizierung sicher auf externe Ressourcen zuzugreifen.
Das folgende Beispiel zeigt, wie Ihr in Agent Runtime ausgeführter Agent die OAuth-Zustimmung von Benutzern anfordern kann, sodass sie sich mit ihrem Google-Konto authentifizieren und den Agenten autorisieren können, auf ihre Google Drive-Inhalte zuzugreifen.
Weitere Informationen zum Einrichten von Identitäten finden Sie unter [Erste](identity-getting-started.md) Schritte mit Identity. AgentCore
### Schritt 6.1: Anmeldeinformationsanbieter einrichten
Um einen Google Credential Provider einzurichten, müssen Sie:
1. Registrieren Sie Ihre Anwendung bei Google, um die Client-ID und das Client-Geheimnis zu erhalten
1. Erstellen Sie mit der CLI einen OAuth-Anbieter für Anmeldeinformationen. AWS Ersetzen Sie {{your-client-id}} und {{your-client-secret}} durch Ihre tatsächliche Google OAuth2-Client-ID und Ihren geheimen Client-Schlüssel:
```
OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
--name "google-provider" \
--credential-provider-vendor "GoogleOauth2" \
--oauth2-provider-config-input '{
"googleOauth2ProviderConfig": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}
}' \
--output json)
OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
```
**Anmerkung**
Rufen Sie das `callbackUrl` aus der [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)Antwort ab und fügen Sie den URI der Weiterleitungs-URI-Liste Ihrer Google-Anwendung hinzu. Die Callback-URL sollte wie folgt aussehen: https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/ \*\*\*\*\*\*\*\*-\*\*\*\*-\*\*\*\*-\*\*\*\*\*\*\*\*\*\*\*\*
Stellen Sie sicher, dass Ihre Aufrufrolle über die erforderlichen Berechtigungen für den Zugriff auf den Anmeldeinformationsanbieter verfügt.
### Schritt 6.2: Ermöglichen Sie dem Agenten, Google Drive-Inhalte zu lesen
Erstellen Sie ein Tool mit Anmerkungen zum Kern-SDK für Agenten, wie im folgenden Beispiel gezeigt, um den dreistufigen OAuth-Prozess automatisch zu initiieren. Wenn Ihr Agent dieses Tool aufruft, werden die Nutzer aufgefordert, die Autorisierungs-URL in ihrem Browser zu öffnen und dem Agenten die Zustimmung zum Zugriff auf ihr Google Drive zu erteilen.
```
import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
provider_name="google-provider",
scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
auth_flow="USER_FEDERATION", # 3LO flow
on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
force_authentication=True,
callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
print(access_token) #You can see the access_token
# Make API calls...
main(access_token)
asyncio.run(read_from_google_drive(access_token=""))
```
**Anmerkung**
Ein Beispiel für eine Implementierung eines lokalen Callback-Servers zur Verarbeitung der [Sitzungsbindung finden](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html) Sie unter [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py)
**Was passiert hinter den Kulissen**
Wenn dieser Code ausgeführt wird, findet der folgende Prozess statt:
1. Agent Runtime autorisiert das eingehende Token gemäß dem konfigurierten Autorisierer.
1. Agent Runtime tauscht dieses Token über die `bedrock-agentcore:GetWorkloadAccessTokenForJWT` API gegen ein Workload-Zugriffstoken aus und übermittelt es über den Payload-Header an Ihren Agentencode. `WorkloadAccessToken`
1. Während des Aufrufs des Tools verwendet Ihr Agent dieses Workload-Zugriffstoken, um die Token Vault-API aufzurufen `bedrock-agentcore:GetResourceOauth2Token` und eine 3LO-Authentifizierungs-URL zu generieren.
1. Ihr Agent sendet diese URL wie in der Methode angegeben an die `on_auth_url` Client-Anwendung.
1. Die Client-Anwendung präsentiert diese URL dem Nutzer, der dem Agenten die Zustimmung erteilt, auf sein Google Drive zuzugreifen.
1. AgentCore Der Identitätsdienst empfängt das Google-Zugriffstoken auf sichere Weise und speichert es im Cache, bis es abläuft, sodass nachfolgende Anfragen des Nutzers zur Verwendung dieses Tokens möglich sind, ohne dass der Nutzer für jede Anfrage seine Zustimmung geben muss.
**Anmerkung**
AgentCore Identity Service speichert das Google-Zugriffstoken im AgentCore Token-Tresor und verwendet dabei die Workload-Identität des Agenten und die Benutzer-ID (aus dem eingehenden JWT-Token, z. B. AWS Cognito-Token) als verbindlichen Schlüssel, sodass wiederholte Zustimmungsanfragen bis zum Ablauf des Google-Tokens vermieden werden.
## Schritt 7: (Optional) Propagieren Sie ein JWT-Token an Runtime AgentCore
Optional können Sie einen Autorisierungsheader an eine AgentCore Runtime übergeben, um Ansprüche zu extrahieren. Dies kann mithilfe der Allowlist-Konfiguration für den Anforderungsheader erfolgen. Weitere Informationen finden Sie unter [RequestHeaderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_RequestHeaderConfiguration.html).
### Schritt 7.1: Ändern Sie Ihren Agentencode, um Header zu lesen
In diesem Schritt nehmen Sie Änderungen an Ihrem Agentencode vor, sodass Sie mithilfe der PyJWT-Bibliothek Ansprüche aus einem JWT-Token dekodieren und extrahieren können.
**requirements.txt**
Fügen Sie der Datei in Ihrem generierten Projekt eine PyJWT-Abhängigkeit hinzu. `requirements.txt`
```
PyJWT
```
**Aktualisieren Sie Ihren Agentencode**
Ändern Sie die Haupt-Agentendatei in Ihrem generierten Projekt (in der Regel `src/main.py` oder ähnlich, je nach Wahl des Frameworks), wie im folgenden Code gezeigt. Sie können die Überprüfung der Tokensignatur hier überspringen, da sie bereits von AgentCore Runtime validiert wurde, als die eingehende Autorisierung durchgeführt wurde.
```
import jwt
import json
....
@app.entrypoint
def invoke(payload, context):
auth_header = context.request_headers.get('Authorization')
if not auth_header:
return None
# Remove "Bearer " prefix if present
token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
try:
# Skip signature validation as agent runtime has validated the token already.
claims = jwt.decode(token, options={"verify_signature": False})
app.logger.info("Claims: %s", json.dumps(claims))
except jwt.InvalidTokenError as e:
app.logger.exception("Invalid JWT token: %s", e)
.....
```
### Schritt 7.2: Erstellen Sie den Agenten mit der Zulassungsliste für den Anforderungsheader
Verwenden Sie die AgentCore CLI, um den Agenten mit der Zulassungsliste für den Anforderungsheader zu konfigurieren. Navigieren Sie zu Ihrem generierten Projektverzeichnis und führen Sie Folgendes aus:
```
agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none
# Now deploy the agent runtime
agentcore deploy
```
**Anmerkung**
Die AgentCore CLI erstellt die Projektstruktur und die Konfigurationsdateien. Passen Sie die Agentenkonfiguration nach `agentcore/agentcore.json` Bedarf an Ihre Framework-Wahl an.
### Schritt 7.3: Rufen Sie Ihren Agenten auf
[Rufen](#oauth-invoke-agent) Sie Ihren Agenten mit OAuth auf und Sie sollten die Ansprüche in Ihren Agentenprotokollen unter Logs sehen. CloudWatch
## Fehlerbehebung
### Wie debugge ich Probleme im Zusammenhang mit Token
Wenn Sie Probleme mit der Token-Authentifizierung haben, können Sie das Token dekodieren, um seinen Inhalt zu überprüfen:
```
echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i