Authentifier et autoriser avec l'authentification entrante et l'authentification sortante

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

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

Amazon Bedrock AgentCore Runtime fournit deux mécanismes d'authentification pour les agents hébergés :

Limitez les appels entrants IAM (SigV4) à votre passerelle

Vous pouvez équiper votre AgentCore environnement d'exécution d'une AgentCore passerelle afin que celle-ci devienne le point d'entrée unique et régi vers l'environnement d'exécution. Vous bénéficiez ainsi d'une autorisation basée sur des règles, d'Amazon Bedrock Guardrails, d'intercepteurs de requêtes et de réponses et d'une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur les raisons et sur la manière de le configurer, voir Façonner votre environnement d'exécution avec une AgentCore passerelle.

Mais cela n'est utile que si les appelants ne peuvent pas atteindre le moteur d'exécution en contournant directement la passerelle. Si votre environnement d'exécution utilise l'autorisation entrante IAM (SigV4) par défaut, vous pouvez limiter l'appel à la passerelle afin que le trafic atteigne le moteur d'exécution uniquement par son intermédiaire. Pour ce faire, associez à l'environnement d'exécution 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 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 basées sur les ressources applicables aux environnements d'exécution, consultez les politiques d'Amazon Resource-based 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 témoin sera autorisé à l'aide des jetons d'accès AWS Cognito. Plus tard, vous découvrirez également comment le code de l'agent peut récupérer des jetons Google au nom de l'utilisateur pour vérifier Google Drive et récupérer du contenu.

Ce que vous allez 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 d'agent squelette avec le framework de votre choix :

agentcore create

La commande vous demandera de :

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, voir Étape 2 : Importer les modules Identity et Auth.

Pour configurer le groupe d'utilisateurs de 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 l'utilisateur. Le jeton est valide pendant 60 minutes par défaut.

Étape 3 (facultatif) : présentez votre environnement d'exécution à l'aide d'une AgentCore passerelle

Vous pouvez équiper votre AgentCore environnement d'exécution d'une AgentCore passerelle afin que celle-ci devienne le point d'entrée unique et régi vers l'environnement d'exécution. Vous bénéficiez ainsi d'une autorisation basée sur des règles, d'Amazon Bedrock Guardrails, d'intercepteurs de requêtes et de réponses et d'une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur les raisons et sur la manière de le configurer, voir Façonner votre environnement d'exécution avec une AgentCore passerelle.

Si vous souhaitez créer cet environnement d'exécution, créez la passerelle dès maintenant, avant de déployer le moteur d'exécution à l'étape suivante. Après le déploiement, vous ajouterez le runtime en tant que cible de passerelle.

Pour vous assurer que les appelants ne peuvent pas contourner la passerelle, limitez le temps d'exécution afin qu'il n'accepte que les appels provenant de cette passerelle. Vous le configurez à l'étape suivante, dans le cadre de l'autorisateur, en utilisant allowedWorkloadConfiguration (voir autorisé WorkloadConfiguration : restreindre l'invocation à votre passerelle).

É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 en utilisant le groupe d'utilisateurs Cognito que vous avez créé. Vous devez 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 fournis, l'autorisateur d'exécution de l'agent vérifiera les deux.

autorisé WorkloadConfiguration : limitez l'invocation à votre passerelle

Le allowedWorkloadConfiguration champ relatif au customJWTAuthorizer restreint les charges de travail de la chaîne d'identité de la demande autorisées à invoquer le runtime. Définissez la charge de travail autorisée pour votre passerelle afin que le moteur d'exécution accepte une demande uniquement lorsque sa chaîne d'identité inclut cette passerelle. C'est ainsi qu'un environnement d'exécution OAuth (JWT) garantit 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 en spécifier 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.

L'exemple suivant crée un environnement d'exécution d'agent qui restreint l'invocation à une AgentCore passerelle spécifique par son ARN. La spécification hostingEnvironments seule est le moyen le plus simple d'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 son nom d'identité de 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 de son identité de 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 le runtime de l'agent. Les exemples suivants montrent comment procéder avec la AgentCore CLI ou le AWS SDK pour Python (Boto3). Notez l'ARN d'exécution de l'agent indiqué dans la sortie : vous en aurez besoin pour appeler l'agent à l'étape suivante.

Étape 5 : utilisez le jeton 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')

Procédez à l'appel de l'agent en suivant le reste des instructions suivantes.

Appelez l'agent avec OAuth.

Réponses aux erreurs OAuth

OAuth-configured les agents respectent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est absente, 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 porteur n'est fourni dans l'en-tête d'autorisation, 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 figurant dans l' WWW-Authenticate en-tête pointe vers l'API Protected Resource Metadata (PRM). 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 accéder aux outils à l'aide d'OAuth

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

L'exemple suivant montre comment votre agent exécuté dans Agent Runtime peut demander le consentement OAuth des utilisateurs, leur permettant 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 avec AgentCore Identity.

É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 : Permettre à l'agent de lire le contenu de Google Drive

Créez un outil avec les annotations du SDK principal de l'agent, comme indiqué 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) Propagation d'un jeton JWT vers Runtime AgentCore

Vous pouvez éventuellement transmettre un en-tête d'autorisation à un AgentCore environnement d'exécution pour extraire des revendications. Cela peut être fait en utilisant la configuration de la liste d'autorisation des en-têtes 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.

requirements.txt

Ajoutez une dépendance PyJWT au requirements.txt fichier dans votre projet généré.

PyJWT

Mettez à jour votre code d'agent

Modifiez le fichier d'agent principal de votre projet généré (généralement src/main.py ou similaire, selon le framework que vous avez choisi) comme indiqué dans le code suivant. Vous pouvez ignorer la validation de la signature du jeton ici puisqu'elle a déjà été validée par AgentCore Runtime lorsque l'autorisation entrante a été effectuée.

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 : Création de l'agent avec la liste d'autorisation d'en-tête de demande

Utilisez la AgentCore CLI pour configurer l'agent avec l'en-tête de demande allowlist. Accédez au répertoire de projet que vous avez généré et exécutez :

agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none

# Now deploy the agent runtime
agentcore deploy

Étape 7.3 : Invoquez votre agent

Invoquez votre agent en utilisant 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 avec l'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 :