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 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/

Informationen zur Verwendung von OAuth mit einem MCP-Server finden Sie unter Bereitstellen von MCP-Servern in Runtime. AgentCore

Amazon Bedrock AgentCore Runtime bietet zwei Authentifizierungsmechanismen für gehostete Agenten:

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

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 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"
                }
            }
        }
    ]
}

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:

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

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:

Folgendes wird generiert:

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.

So richten Sie den Cognito-Benutzerpool ein und erstellen einen Benutzer

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

Wenn Sie diese Runtime bereitstellen möchten, erstellen Sie jetzt das Gateway, bevor Sie die Runtime im nächsten Schritt bereitstellen. Nach der Bereitstellung fügen Sie die Runtime als Gateway-Ziel 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 Ihr Gateway).

Schritt 4: Stellen Sie Ihren Agenten bereit

{
    "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"
        }
    }
}

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.

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.

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"
    ]
}

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.

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.

{
    "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.

OAuth-Fehlerantworten

OAuth-configured Agenten folgen den Authentifizierungsstandards RFC 6749 (OAuth 2.0). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß RFC 7235) 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.

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 Schritte mit Identity. AgentCore

Schritt 6.1: Anmeldeinformationsanbieter einrichten

Um einen Google Credential Provider einzurichten, müssen Sie:

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=""))

Was passiert hinter den Kulissen

Wenn dieser Code ausgeführt wird, findet der folgende Prozess statt:

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.

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

Schritt 7.3: Rufen Sie Ihren Agenten auf

Rufen 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<l; i++) printf "="; print "" }' | base64 -D | jq

Dadurch wird die Nutzlast des Tokens ausgegeben, die wie folgt aussieht:

{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}

Überprüfen Sie bei der Behebung von Token-Problemen Folgendes: