Autentica y autoriza con Autenticación entrante y Autenticación saliente

En esta sección, se muestra cómo implementar la autenticación y la autorización en el tiempo de ejecución de los agentes mediante los tokens portadores de OAuth y JWT con identidad. AgentCore Aprenderás a configurar los grupos de usuarios de Cognito, configurar el tiempo de ejecución de tus agentes para la autenticación con 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, consulta Cómo implementar servidores MCP en tiempo de ejecución. AgentCore

Amazon Bedrock AgentCore Runtime proporciona dos mecanismos de autenticación para los agentes alojados:

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

Puede configurar su AgentCore entorno de ejecución con una AgentCore puerta de enlace para que ésta se convierta en el punto de entrada único y controlado al tiempo de ejecución, lo que le permitirá disponer de autorizaciones basadas en políticas, barreras de protección de Amazon Bedrock, interceptores de solicitudes y respuestas y una observabilidad unificada, todo ello aplicado fuera del entorno del propio agente. Para conocer todos los motivos y saber cómo configurarlo, consulte Front your runtime with an Gateway. AgentCore

Pero esto solo es útil si las personas que llaman no pueden acceder directamente al motor de ejecución sin pasar por la puerta de enlace. Si tu motor de ejecución usa la autorización entrante predeterminada de IAM (SIGv4), puedes restringir la invocación a la puerta de enlace para que el tráfico llegue al tiempo de ejecución únicamente a través de ella. Para lograrlo, adjunta al tiempo de ejecución una política basada en los 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 en el tiempo de ejecución, por lo que la función de puerta de enlace es el principal que invoca el tiempo de ejecución. Permita esa función y añada una función explícita Deny para cada otra entidad principal, 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 de tiempos de ejecución basadas en recursos, consulte las políticas de Amazon Bedrock. Resource-based 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

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

Qué aprenderás

En esta guía, aprenderás cómo:

Requisitos previos

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

Paso 1: Crea tu proyecto de agente

Usa el agentcore create comando para configurar un proyecto vacío. Añada el JWT-authorized agente después de crear los recursos de Cognito en el paso 2.

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

Esto genera:

Paso 2: Configurar AWS Grupo de usuarios de Cognito y adición de un usuario

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

Para obtener más información, consulta 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, agrega un usuario y genera un token portador para el usuario. El token es válido durante 60 minutos de forma predeterminada.

Paso 3 (opcional): mejora tu tiempo de ejecución con un AgentCore Gateway

Puede configurar su AgentCore tiempo de ejecución con una AgentCore puerta de enlace para que ésta se convierta en el punto de entrada único y controlado al tiempo de ejecución, lo que le proporcionará una autorización basada en políticas, barreras de protección de Amazon Bedrock, interceptores de solicitudes y respuestas y una observabilidad unificada, todo ello fuera del entorno del propio agente. Para conocer todos los motivos y saber cómo configurarlo, consulte Front your runtime with an Gateway. AgentCore

Si desea anticipar 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 puerta de enlace.

Para asegurarte de que las personas que llaman no puedan eludir la puerta de enlace, restringe el tiempo de ejecución para que solo acepte las invocaciones desde esa puerta de enlace. allowedWorkloadConfigurationUtilízalo como se describe en PermitidoWorkloadConfiguration: restringe la invocación a tu puerta de enlace. La AgentCore CLI no configura este campo. Utilice la API del AgentCore plano de control.

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 desplegará su agente con la autorización de JWT mediante el grupo de usuarios de Cognito que creó. Tendrá que crear un agente con la configuración del 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 tanto client_id como aud, el autorizador del tiempo de ejecución del agente verificará ambos.

permitidoWorkloadConfiguration: restringe la invocación a tu puerta de enlace

El allowedWorkloadConfiguration campo correspondiente customJWTAuthorizer restringe qué cargas de trabajo de la cadena de identidad de la solicitud 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 acepte una solicitud solo cuando su cadena de identidad incluya esa puerta de enlace. De esta forma, un motor de ejecución de OAuth (JWT) hace que el tráfico llegue solo a través de la puerta de enlace que configuraste en el paso 3.

Las cargas de trabajo permitidas se proporcionan mediante cualquiera de los siguientes campos. Puedes 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 proporciones ambos campos.

La siguiente configuración del autorizador restringe la invocación a una AgentCore puerta de enlace específica mediante su ARN. La forma más sencilla de hostingEnvironments permitir una puerta de enlace es especificarla por 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 el nombre de identidad de la 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 tiempo de ejecución del agente

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). Observe el ARN en tiempo de ejecución del agente que aparece 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 con 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 no autorizada 401 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

Si no se proporciona ningún token 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 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 acceder de forma segura 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 a los usuarios el consentimiento de OAuth, lo que les permite autenticarse con su cuenta de Google y autorizar al agente a acceder a su contenido de Google Drive.

Para obtener más información sobre la configuración de la identidad, consulta Cómo empezar a usar la identidad. 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: Permita que el agente lea el contenido de Google Drive

Crea una herramienta con las anotaciones principales del SDK del agente, como se muestra en el siguiente ejemplo, para iniciar automáticamente el proceso de OAuth en tres etapas. 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 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é ocurre entre bastidores

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

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

Si lo desea, puede pasar un encabezado de autorización a un AgentCore Runtime para extraer las notificaciones. Esto se puede hacer mediante la configuración de lista de permitidos del encabezado de la 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, realizas cambios en tu código de agente para poder decodificar y extraer las reclamaciones de un token de JWT mediante la biblioteca PyJWT.

Dependencias de Python

Agregue PyJWT a los agentes generados: pyproject.toml

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

Actualiza tu código de agente

app/OAuthAgent/main.pyModifícalo como se muestra en el siguiente código. Aquí puedes omitir la validación de la firma del token porque AgentCore Runtime ya validó el token durante la autorización 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)

    .....

Paso 7.2: Despliegue el agente actualizado

El agentcore add agent comando del paso 4 ya configuró la lista de permitidos del encabezado de la Authorization solicitud. Implemente la actualización del código:

agentcore deploy

Paso 7.3: Invoca a tu agente

Invoca a tu agente mediante OAuth y verás las reclamaciones en los registros de inicio de sesión 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 al siguiente:

{
    "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 los tokens, comprueba lo siguiente: