Authentifiez-vous et autorisez avec Inbound Auth et Outbound Auth

Cette section explique comment implémenter l'authentification et l'autorisation pour l'exécution de votre agent à l'aide des jetons porteurs OAuth et JWT avec Identity. AgentCore Vous apprendrez à configurer des groupes d'utilisateurs Cognito, à configurer l'environnement d'exécution de votre agent pour l'authentification JWT (Inbound Auth) et à implémenter l' OAuth-based accès à des ressources tierces (Auth sortante).

Pour un exemple complet, voirhttps://github.com/awslabs/amazon-bedrock-agentcore-samples/.

Pour plus d'informations sur l'utilisation d'OAuth avec un serveur MCP, voir Déployer des serveurs MCP dans Runtime. AgentCore

L' AgentCore environnement d'exécution Amazon Bedrock fournit deux mécanismes d'authentification pour les agents hébergés :

Restreindre les appels entrants IAM (Sigv4) à votre passerelle

Vous pouvez intégrer une AgentCore passerelle à votre AgentCore environnement d'exécution afin que celle-ci devienne le point d'entrée unique et régi du runtime, ce qui vous donne accès à une autorisation basée sur des règles, à Amazon Bedrock Guardrails, à des intercepteurs de demandes et de réponses et à une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur la justification complète et sur la manière de configurer cela, consultez la section Intégrez votre environnement d'exécution à l'aide d'une AgentCore passerelle.

Mais cela n'est utile que si les appelants ne peuvent pas accéder directement au runtime en contournant la passerelle. Si votre environnement d'exécution utilise l'autorisation entrante IAM (Sigv4) par défaut, vous pouvez restreindre l'appel à la passerelle afin que le trafic n'atteigne le moteur d'exécution que par son intermédiaire. Pour ce faire, associez au runtime une politique basée sur les ressources qui limite l'invocation au rôle d'exécution de votre passerelle. La passerelle assume son rôle de service pour signer les demandes adressées au moteur d'exécution. Le rôle de passerelle est donc le principal qui invoque le moteur d'exécution. Autorisez ce rôle et ajoutez un rôle explicite Deny pour tous les autres principaux afin qu'aucune autre identité ne puisse invoquer le runtime, même avec une politique permissive basée sur l'identité. Pour plus d'informations sur les politiques d'exécution basées sur les ressources, consultez les politiques Resource-based relatives à 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"
                }
            }
        }
    ]
}

Exemple d'autorisation entrante JWT et d'accès sortant OAuth

Ce guide explique le processus de configuration de l'environnement d'exécution de votre agent pour qu'il soit invoqué avec un jeton d'accès conforme à OAuth au format JWT. L'agent d'échantillonnage sera autorisé à l'aide de jetons d'accès AWS Cognito. Plus tard, vous découvrirez également comment le code d'agent peut récupérer des jetons Google pour le compte de l'utilisateur afin qu'il consulte Google Drive et récupère le contenu.

Ce que tu vas apprendre

Dans ce guide, vous allez apprendre à :

Conditions préalables

Avant de commencer, assurez-vous d'avoir :

Étape 1 : Créez votre projet d'agent

Utilisez la agentcore create commande pour configurer un projet vide. Vous ajoutez l' JWT-authorized agent après avoir créé les ressources Cognito à l'étape 2.

agentcore create --project-name OAuthAgentProject --no-agent
cd OAuthAgentProject

Cette commande génère :

Étape 2 : Configuration AWS Groupe d'utilisateurs Cognito et ajout d'un utilisateur

Pour configurer un groupe d'utilisateurs Cognito et créer un utilisateur, vous allez utiliser un script shell qui automatise le processus.

Pour plus d'informations, consultez Étape 2 : Importer les modules Identity et Auth.

Pour configurer le groupe d'utilisateurs Cognito et créer un utilisateur

Ce script crée un groupe d'utilisateurs Cognito, un client de groupe d'utilisateurs, ajoute un utilisateur et génère un jeton porteur pour cet utilisateur. Le jeton est valide pendant 60 minutes par défaut.

Étape 3 (Facultatif) : configurez votre environnement d'exécution avec une AgentCore passerelle

Vous pouvez intégrer une AgentCore passerelle à votre AgentCore environnement d'exécution afin que celle-ci devienne le point d'entrée unique et régi du runtime, ce qui vous donne accès à une autorisation basée sur des règles, à Amazon Bedrock Guardrails, à des intercepteurs de demandes et de réponses et à une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur la justification complète et sur la manière de configurer cela, consultez la section Intégrez votre environnement d'exécution à l'aide d'une AgentCore passerelle.

Si vous souhaitez lancer ce runtime, créez la passerelle dès maintenant, avant de déployer le runtime à l'étape suivante. Après le déploiement, vous allez ajouter le runtime en tant que cible de passerelle.

Pour vous assurer que les appelants ne peuvent pas contourner la passerelle, limitez le runtime pour qu'il n'accepte que les appels provenant de cette passerelle. Utilisez allowedWorkloadConfiguration comme décrit dans Autorisé WorkloadConfiguration : limitez l'invocation à votre passerelle. La AgentCore CLI ne configure pas ce champ. Utilisez l'API du AgentCore plan de contrôle.

Étape 4 : Déployez votre agent

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

Vous allez maintenant déployer votre agent avec l'autorisation JWT à l'aide du groupe d'utilisateurs Cognito que vous avez créé. Vous devrez créer un agent avec une configuration d'autorisation. Le tableau suivant représente les différents paramètres de configuration de l'autorisateur et la manière dont nous les utilisons pour valider le jeton entrant.

Si client_id et aud sont tous deux fournis, l'autorisateur d'exécution de l'agent vérifiera les deux.

autorisé WorkloadConfiguration : limitez l'invocation à votre passerelle

Le allowedWorkloadConfiguration champ sur les customJWTAuthorizer limites des charges de travail de la chaîne d'identité de la demande qui sont autorisées à invoquer le runtime. Définissez la charge de travail autorisée pour votre passerelle afin que le moteur d'exécution n'accepte une demande que lorsque sa chaîne d'identité inclut cette passerelle. C'est ainsi qu'un environnement d'exécution OAuth (JWT) fait en sorte que le trafic n'arrive que via la passerelle que vous avez configurée à l'étape 3.

Vous indiquez les charges de travail autorisées à l'aide de l'un des champs suivants. Vous pouvez spécifier l'un ou les deux : une demande est acceptée si sa chaîne d'identité correspond à une entrée dans l'un ou l'autre des champs. Vous n'avez donc pas besoin de fournir les deux.

La configuration d'autorisation suivante limite l'appel à une AgentCore passerelle spécifique par son ARN. La spécification hostingEnvironments seule est la méthode la plus simple pour autoriser une passerelle :

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

Vous pouvez également identifier la passerelle par le nom d'identité de sa charge de travail ou spécifier les deux champs. Lorsque les deux sont présents, une demande est autorisée si elle correspond à une entrée dans l'un ou l'autre des champs. L'allowedWorkloadConfigurationextrait suivant autorise deux passerelles différentes, l'une identifiée par son ARN et l'autre par le nom d'identité de sa charge de travail :

"allowedWorkloadConfiguration": {
    "hostingEnvironments": [
        {
            "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
        }
    ],
    "workloadIdentities": [
        "my-gateway-2-workload-identity"
    ]
}

Création et déploiement de l'environnement d'exécution de l'agent

Une fois la configuration de votre autorisateur prête, créez et déployez l'environnement d'exécution de l'agent. Les exemples suivants montrent comment procéder à l'aide de l' AgentCore interface de ligne de commande ou du AWS SDK pour Python (Boto3). Notez l'ARN d'exécution de l'agent figurant sur la sortie. Vous en aurez besoin pour appeler l'agent à l'étape suivante.

Étape 5 : Utilisez le jeton du porteur pour invoquer votre agent

Maintenant que votre agent est déployé avec l'autorisation JWT, vous pouvez l'invoquer à l'aide du jeton porteur.

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

Invoquer l'agent

Récupérez un jeton porteur pour l'utilisateur que vous avez créé avec Amazon Cognito.

# 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')

Passez à l'appel de l'agent en suivant le reste des instructions suivantes.

Invoquez l'agent avec OAuth.

Réponses aux erreurs OAuth

OAuth-configured les agents suivent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est manquante, le service renvoie une réponse 401 Unauthorized avec un WWW-Authenticate en-tête (conformément à la RFC 7235), permettant aux clients de découvrir les points de terminaison du serveur d'autorisation via l'API. GetRuntimeProtectedResourceMetadata

401 Non autorisé - Authentification manquante

Lorsqu'aucun jeton Bearer n'est fourni dans l'en-tête Authorization, la réponse est la suivante :

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

L'resource_metadataURL de l' WWW-Authenticate en-tête pointe vers l'API PRM (Protected Resource Metadata). L'API PRM permet aux clients de découvrir quels serveurs d'autorisation protègent cet agent et leurs URL de point de terminaison OAuth.

Étape 6 : configurer votre agent pour qu'il accède aux outils à l'aide d'OAuth

Dans cette section, vous allez apprendre à connecter votre code d'agent aux fournisseurs AgentCore d'informations d'identification pour un accès sécurisé à des ressources externes à l'aide de l'authentification OAuth2.

L'exemple suivant montre comment votre agent qui s'exécute dans Agent Runtime peut demander le consentement OAuth aux utilisateurs, leur permettant ainsi de s'authentifier avec leur compte Google et d'autoriser l'agent à accéder à leur contenu Google Drive.

Pour plus d'informations sur la configuration de l'identité, voir Commencer à utiliser AgentCore l'identité.

Étape 6.1 : Configuration des fournisseurs d'informations d'identification

Pour configurer un fournisseur d'informations d'identification Google, vous devez :

Assurez-vous que votre rôle d'invocation dispose des autorisations nécessaires pour accéder au fournisseur d'informations d'identification.

Étape 6.2 : Autoriser l'agent à lire le contenu de Google Drive

Créez un outil avec les annotations du SDK principal de l'agent, comme illustré dans l'exemple suivant, pour lancer automatiquement le processus OAuth en trois étapes. Lorsque votre agent invoque cet outil, les utilisateurs sont invités à ouvrir l'URL d'autorisation dans leur navigateur et à autoriser l'agent à accéder à leur Google Drive.

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

Que se passe-t-il dans les coulisses

Lorsque ce code s'exécute, le processus suivant se produit :

Étape 7 : (Facultatif) Propager un jeton JWT vers Runtime AgentCore

Vous pouvez éventuellement transmettre un en-tête Authorization à un AgentCore Runtime pour extraire les revendications. Cela peut être fait en utilisant la configuration de la liste d'autorisations de l'en-tête de demande. Pour de plus amples informations, veuillez consulter RequestHeaderConfiguration.

Étape 7.1 : modifiez le code de votre agent pour lire les en-têtes

Au cours de cette étape, vous apportez des modifications au code de votre agent afin de pouvoir décoder et extraire les revendications d'un jeton JWT à l'aide de la bibliothèque PyJWT.

Dépendances Python

Ajoutez PyJWT à l'agent généré : pyproject.toml

cd app/OAuthAgent
uv add PyJWT
cd ../..

Mettez à jour votre code d'agent

Modifiez app/OAuthAgent/main.py comme indiqué dans le code suivant. Vous pouvez ignorer la validation de la signature du jeton ici car AgentCore Runtime a déjà validé le jeton lors de l'autorisation entrante.

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)

    .....

Étape 7.2 : Déploiement de l'agent mis à jour

La agentcore add agent commande de l'étape 4 a déjà configuré la liste d'autorisation des en-têtes de Authorization demande. Déployez la mise à jour du code :

agentcore deploy

Étape 7.3 : Invoquer votre agent

Invoquez votre agent à l'aide d'OAuth et vous devriez voir les réclamations dans les journaux de votre agent. CloudWatch

Résolution des problèmes

Comment résoudre les problèmes liés aux jetons

Si vous rencontrez des problèmes d'authentification par jeton, vous pouvez décoder le jeton pour inspecter son contenu :

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

Cela produira la charge utile du jeton, qui ressemble à :

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

Lorsque vous résolvez des problèmes liés aux jetons, vérifiez les points suivants :