Autenticar y autorizar con autenticación entrante y autenticación saliente

En esta sección, se muestra cómo implementar la autenticación y la autorización para el tiempo de ejecución de su agente mediante los tokens portadores de OAuth y JWT con Identity. AgentCore Aprenderá a configurar grupos de usuarios de Cognito, configurar el tiempo de ejecución del agente para la autenticación JWT (autenticación entrante) e implementar el OAuth-based acceso a recursos de terceros (autenticación saliente).

Para ver un ejemplo completo, consulte. https://github.com/awslabs/amazon-bedrock-agentcore-samples/

Para obtener información sobre el uso de OAuth con un servidor MCP, consulte Implementación de servidores MCP en tiempo de ejecución. AgentCore

El tiempo de AgentCore ejecución de Amazon Bedrock proporciona dos mecanismos de autenticación para los agentes alojados:

Restrinja la invocación entrante de IAM (SiGv4) a su puerta de enlace

Puede gestionar su AgentCore tiempo de ejecución con una AgentCore puerta de enlace para que la puerta de enlace se convierta en el único punto de entrada gobernado al tiempo de ejecución, lo que le proporciona una autorización basada en políticas, Amazon Bedrock Guardrails, interceptores de solicitudes y respuestas y una observabilidad unificada, todo ello aplicado fuera del entorno del agente. Para obtener información completa sobre los motivos y cómo configurarlo, consulte Cómo gestionar su tiempo de ejecución con una puerta de enlace. AgentCore

Sin embargo, esto solo es útil si las personas que llaman no pueden llegar al motor de ejecución directamente sin pasar por la puerta de enlace. Si su entorno de ejecución utiliza la autorización de entrada predeterminada de IAM (SiGv4), puede restringir la invocación a la puerta de enlace para que el tráfico llegue al entorno de ejecución únicamente a través de ella. Para lograrlo, adjunte al tiempo de ejecución una política basada en recursos que restrinja la invocación a la función de ejecución de la puerta de enlace. La puerta de enlace asume su función de servicio para firmar las solicitudes al tiempo de ejecución, por lo que la función de puerta de enlace es la principal que invoca el tiempo de ejecución. Permita esa función y añada una explícita Deny para todos los demás principios, de modo que ninguna otra identidad pueda invocar el tiempo de ejecución, incluso con una política permisiva basada en la identidad. Para obtener más información sobre las políticas basadas en recursos en tiempos de ejecución, consulte las políticas de 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"
                }
            }
        }
    ]
}

Ejemplo de autorización entrante de JWT y acceso saliente de OAuth

Esta guía explica el proceso de configuración del tiempo de ejecución del agente para que se invoque con un token de acceso compatible con OAuth y en formato JWT. El agente de muestra estará autorizado mediante los tokens de acceso de AWS Cognito. Más adelante, también aprenderá cómo el código del agente puede obtener tokens de Google en nombre del usuario para consultar Google Drive y buscar contenido.

¿Qué aprenderás

En esta guía, aprenderás a:

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

Paso 1: Crea tu proyecto de agente

Utilice el agentcore create comando para configurar un proyecto de agente básico con el marco que prefiera:

agentcore create

El comando le pedirá que:

Esto genera:

Paso 2: Configurar AWS Grupo de usuarios de Cognito y añadir un usuario

Para configurar un grupo de usuarios de Cognito y crear un usuario, utilizará un script de shell que automatiza el proceso.

Para obtener más información, consulte el paso 2: Importar los módulos de identidad y autenticación.

Para configurar el grupo de usuarios de Cognito y crear un usuario

Este script crea un grupo de usuarios de Cognito, un cliente de grupo de usuarios, añade un usuario y genera un token de portador para el usuario. De forma predeterminada, el token es válido durante 60 minutos.

Paso 3 (opcional): Controle su tiempo de ejecución con una AgentCore puerta de enlace

Puede gestionar su AgentCore tiempo de ejecución con una AgentCore puerta de enlace para que la puerta de enlace se convierta en el único punto de entrada gobernado al tiempo de ejecución, lo que le proporciona una autorización basada en políticas, Amazon Bedrock Guardrails, interceptores de solicitudes y respuestas y una observabilidad unificada, todo ello aplicado fuera del entorno del agente. Para obtener información completa sobre los motivos y cómo configurarlo, consulte Cómo gestionar su tiempo de ejecución con una puerta de enlace. AgentCore

Si desea aprovechar este tiempo de ejecución, cree la puerta de enlace ahora, antes de implementar el tiempo de ejecución en el siguiente paso. Tras la implementación, añadirá el tiempo de ejecución como destino de la puerta de enlace.

Para asegurarte de que las personas que llaman no puedan pasar por alto la puerta de enlace, restringe el tiempo de ejecución para que solo acepte invocaciones desde esa puerta de enlace. Esto se configura en el siguiente paso, como parte del autorizador, mediante allowedWorkloadConfiguration (consulte PermitidoWorkloadConfiguration: restringir la invocación a su puerta de enlace).

Paso 4: Despliegue su agente

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

Ahora implementará su agente con la autorización de JWT mediante el grupo de usuarios de Cognito que creó. Deberá crear un agente con la configuración de autorizador. La siguiente tabla representa los distintos parámetros de configuración del autorizador y cómo los utilizamos para validar el token entrante.

Si se proporcionan client_id y aud, el autorizador de tiempo de ejecución del agente verificará ambos.

permitidoWorkloadConfiguration: restrinja la invocación a su puerta de enlace

El allowedWorkloadConfiguration campo correspondiente customJWTAuthorizer restringe las cargas de trabajo de la cadena de identidad de la solicitud que pueden invocar el tiempo de ejecución. Configura la carga de trabajo permitida en tu puerta de enlace para que el motor de ejecución solo acepte una solicitud cuando su cadena de identidad incluya esa puerta de enlace. Así es como un entorno de ejecución de OAuth (JWT) exige que el tráfico llegue únicamente a través de la puerta de enlace que configuraste en el paso 3.

Las cargas de trabajo permitidas se proporcionan mediante uno de los siguientes campos. Puede especificar uno o ambos: se acepta una solicitud si su cadena de identidad coincide con una entrada de cualquiera de los campos, por lo que no es necesario que proporcione ambos.

El siguiente ejemplo crea un agente en tiempo de ejecución que restringe la invocación a una AgentCore puerta de enlace específica por su ARN. La forma más sencilla de permitir una puerta de enlace es especificarla por hostingEnvironments sí sola:

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

Como alternativa, puede identificar la puerta de enlace por su nombre de identidad de carga de trabajo o especificar ambos campos. Cuando ambos están presentes, se permite una solicitud si coincide con una entrada de cualquiera de los campos. El siguiente allowedWorkloadConfiguration fragmento permite dos puertas de enlace diferentes, una identificada por su ARN y otra por su nombre de identidad de carga de trabajo:

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

Cree e implemente el agente (en tiempo de ejecución)

Con la configuración del autorizador lista, cree e implemente el tiempo de ejecución del agente. Los siguientes ejemplos muestran cómo hacerlo con la AgentCore CLI o el AWS SDK para Python (Boto3). Anote el ARN del tiempo de ejecución del agente en el resultado; lo necesitará para invocar al agente en el siguiente paso.

Paso 5: Usa el token de portador para invocar a tu agente

Ahora que tu agente está desplegado con la autorización de JWT, puedes invocarlo con el token portador.

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

Invoca al agente

Obtenga un token de portador para el usuario que creó con 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')

Proceda a invocar al agente siguiendo el resto de las instrucciones siguientes.

Invoca al agente con OAuth.

Respuestas de error de OAuth

OAuth-configured los agentes siguen los estándares de autenticación RFC 6749 (OAuth 2.0). Cuando falta la autenticación, el servicio devuelve una respuesta 401 no autorizada con un WWW-Authenticate encabezado (según la RFC 7235), lo que permite a los clientes descubrir los puntos finales del servidor de autorización a través de la API. GetRuntimeProtectedResourceMetadata

401 No autorizado: falta la autenticación

Cuando no se proporciona ningún identificador de portador en el encabezado de autorización, la respuesta es:

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

La resource_metadata URL del WWW-Authenticate encabezado apunta a la API de metadatos de recursos protegidos (PRM). La API PRM permite a los clientes descubrir qué servidores de autorización protegen a este agente y a sus URL de punto final de OAuth.

Paso 6: Configure su agente para que acceda a las herramientas mediante OAuth

En esta sección, aprenderás a conectar tu código de agente con los proveedores de AgentCore credenciales para un acceso seguro a los recursos externos mediante la autenticación OAuth2.

En el siguiente ejemplo, se muestra cómo un agente que se ejecuta en Agent Runtime puede solicitar el consentimiento de OAuth a los usuarios, lo que les permite autenticarse con su cuenta de Google y autorizar al agente a acceder al contenido de Google Drive.

Para obtener más información sobre cómo configurar la identidad, consulte Primeros pasos con Identity. AgentCore

Paso 6.1: Configurar los proveedores de credenciales

Para configurar un proveedor de credenciales de Google, debes:

Asegúrese de que su función de invocación tenga los permisos necesarios para acceder al proveedor de credenciales.

Paso 6.2: Permite que el agente lea el contenido de Google Drive

Crea una herramienta con las anotaciones del SDK del núcleo del agente, como se muestra en el siguiente ejemplo, para iniciar automáticamente el triple proceso de OAuth. Cuando tu agente invoque esta herramienta, se les pedirá a los usuarios que abran la URL de autorización en su navegador y den su consentimiento para que el agente acceda a su 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=""))

¿Qué sucede entre bastidores

Cuando se ejecuta este código, se produce el siguiente proceso:

Paso 7: (opcional) Propagar un token JWT a Runtime AgentCore

Si lo desea, puede pasar un encabezado de autorización a un AgentCore Runtime para extraer las reclamaciones. Esto se puede hacer mediante la configuración de lista de permisos del encabezado de solicitud. Para obtener más información, consulte RequestHeaderConfiguration.

Paso 7.1: Modifique el código de su agente para leer los encabezados

En este paso, realiza cambios en su código de agente para poder decodificar y extraer las reclamaciones de un token de JWT mediante la biblioteca PyJWT.

requirements.txt

Agrega la dependencia de PyJWT al archivo del proyecto generadorequirements.txt.

PyJWT

Actualice su código de agente

Modifique el archivo de agente principal del proyecto generado (normalmente src/main.py o similar, según el marco que elija) como se muestra en el código siguiente. Aquí puedes omitir la validación de la firma del token, ya que AgentCore Runtime ya la validó cuando se realizó la autorización de entrada.

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)

    .....

Paso 7.2: Crea el agente con la lista de permitidos del encabezado de la solicitud

Utilice la AgentCore CLI para configurar el agente con la lista de permisos del encabezado de solicitud. Navegue hasta el directorio de proyectos generado y ejecute:

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

# Now deploy the agent runtime
agentcore deploy

Paso 7.3: Invoca a tu agente

Invoca a tu agente mediante OAuth y verás las reclamaciones en los registros de tu agente. CloudWatch

Resolución de problemas

¿Cómo depurar problemas relacionados con los tokens

Si tienes problemas con la autenticación del token, puedes decodificarlo para inspeccionar su contenido:

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

Esto generará la carga útil del token, que tiene un aspecto similar a:

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

Cuando resuelvas problemas con el token, comprueba lo siguiente: