Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Cree su primer agente autenticado

Este tutorial de introducción le explica cómo crear un agente autenticado completo desde cero con Amazon Bedrock AgentCore Identity y le ayudará a empezar a implementar las funciones de identidad en las aplicaciones de sus agentes. Aprenderá a configurar su entorno de desarrollo, a crear una infraestructura de autenticación con Cognito, a implementar su agente en AgentCore Runtime y a probar todo el flujo de trabajo de autenticación.

Al final de este tutorial, tendrás un agente completamente implementado que puede autenticar a los usuarios mediante los flujos de OAuth2, obtener los tokens de acceso de forma segura y demostrar el ciclo de vida completo de la administración de identidades. Su agente funcionará en AgentCore Runtime con los permisos de IAM adecuados, lo que creará un entorno de laboratorio de pruebas en el que podrá demostrar y probar las capacidades de integración.

Requisitos previos

Antes de comenzar, asegúrese de que dispone de lo siguiente:

Este tutorial requiere que tenga un servidor de autorización de OAuth 2.0. Si no tiene uno, el paso 1 creará uno para usted mediante los grupos de usuarios de Amazon Cognito. Si tiene un servidor de autorización de OAuth 2.0 con un identificador de cliente, un secreto de cliente y un usuario configurado, puede continuar con el paso 2. Este servidor de autorización actuará como proveedor de credenciales de recursos y representará a la autoridad que otorga al agente un token de acceso OAuth 2.0 saliente.

Instale el SDK y las dependencias

Cree una carpeta para esta guía, cree un entorno virtual de Python e instale el AgentCore SDK y el SDK de AWS Python (boto3).

mkdir agentcore-identity-quickstart
cd agentcore-identity-quickstart
python3 -m venv .venv
source .venv/bin/activate
pip install bedrock-agentcore boto3 strands-agents pyjwt

Paso 1: Crear un grupo de usuarios de Cognito (opcional)

Este tutorial requiere un servidor de autorización de OAuth 2.0. Si no tiene uno disponible para realizar pruebas o si desea mantener la prueba separada de su servidor de autorización, este script utilizará sus AWS credenciales para configurar una instancia de Amazon Cognito y utilizarla como servidor de autorización. El script creará:

Al eliminar el grupo de usuarios de Cognito, AgentCoreIdentityQuickStartPool también se eliminarán el client_id y el usuario asociados.

Puede guardar este script como create_cognito.sh y ejecutarlo desde la línea de comandos, o pegar el script en la línea de comandos.

#!/bin/bash

REGION=$(aws configure get region)

# Create user pool
USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name AgentCoreIdentityQuickStartPool \
  --query 'UserPool.Id' \
  --no-cli-pager \
  --output text)

# Create user pool domain
DOMAIN_NAME="agentcore-quickstart-$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 5)"
aws cognito-idp create-user-pool-domain \
  --domain $DOMAIN_NAME \
  --no-cli-pager \
  --user-pool-id $USER_POOL_ID > /dev/null

# Create user pool client with secret and hosted UI settings
CLIENT_RESPONSE=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name AgentCoreQuickStart \
  --generate-secret \
  --allowed-o-auth-flows "code" \
  --allowed-o-auth-scopes "openid" "profile" "email" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers "COGNITO" \
  --query 'UserPoolClient.{ClientId:ClientId,ClientSecret:ClientSecret}' \
  --output json)

CLIENT_ID=$(echo $CLIENT_RESPONSE | jq -r '.ClientId')
CLIENT_SECRET=$(echo $CLIENT_RESPONSE | jq -r '.ClientSecret')

# Generate random username and password
USERNAME="AgentCoreTestUser$(printf "%04d" $((RANDOM % 10000)))"
PASSWORD="$(LC_ALL=C tr -dc 'A-Za-z0-9!@#$%^&*()_+-=[]{}|;:,.<>?' < /dev/urandom | head -c 16)$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 1)"

# Create user with permanent password
aws cognito-idp admin-create-user \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --output text > /dev/null

aws cognito-idp admin-set-user-password \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --output text > /dev/null \
  --permanent

# Get region

ISSUER_URL="https://cognito-idp.$REGION.amazonaws.com/$USER_POOL_ID/.well-known/openid-configuration"
HOSTED_UI_URL="https://$DOMAIN_NAME.auth.$REGION.amazoncognito.com"

# Output results
echo "User Pool ID: $USER_POOL_ID"
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
echo "Issuer URL: $ISSUER_URL"
echo "Hosted UI URL: $HOSTED_UI_URL"
echo "Test User: $USERNAME"
echo "Test Password: $PASSWORD"

echo ""
echo "# Copy and paste these exports to set environment variables for later use:"
echo "export USER_POOL_ID='$USER_POOL_ID'"
echo "export CLIENT_ID='$CLIENT_ID'"
echo "export CLIENT_SECRET='$CLIENT_SECRET'"
echo "export ISSUER_URL='$ISSUER_URL'"
echo "export HOSTED_UI_URL='$HOSTED_UI_URL'"
echo "export COGNITO_USERNAME='$USERNAME'"
echo "export COGNITO_PASSWORD='$PASSWORD'"

Paso 2: Crear un proveedor de credenciales

Los proveedores de credenciales son la forma en que su agente accede a los servicios externos. Cree un proveedor de credenciales y configúrelo con un cliente de OAuth 2.0 para su servidor de autorización.

Si está utilizando su propio servidor de autorización, defina las variables ISSUER_URL de entorno y CLIENT_SECRET con los valores correspondientes de su servidor de autorización. CLIENT_ID Si utiliza el script anterior para crear un servidor de autorización para usted con Cognito, copie las instrucciones EXPORT del resultado a su terminal para configurar las variables de entorno.

El código de tu agente utilizará este proveedor de credenciales para obtener los tokens de acceso que permitan actuar en nombre de tu usuario.

Paso 2.5: Añade la URL de devolución de llamada a tu servidor de autorización de OAuth 2.0

Para evitar redireccionamientos no autorizados, añade la URL de devolución de llamada recuperada de CreateOauth2CredentialProvider o GetOauth2CredentialProvider a tu servidor de autorización de OAuth 2.0.

Si utiliza el script anterior para crear un servidor de autorización con Cognito, copie las instrucciones EXPORT del resultado en su terminal para establecer las variables de entorno y actualizar el cliente del grupo de usuarios de Cognito con la URL de devolución de llamada del proveedor de credenciales de OAuth2.

#!/bin/bash
aws cognito-idp update-user-pool-client \
    --user-pool-id $USER_POOL_ID \
    --client-id $CLIENT_ID \
    --client-name AgentCoreQuickStart \
    --allowed-o-auth-flows "code" \
    --allowed-o-auth-scopes "openid" "profile" "email" \
    --allowed-o-auth-flows-user-pool-client \
    --supported-identity-providers "COGNITO" \
    --callback-urls "$OAUTH2_CALLBACK_URL"

Paso 3: Cree un agente de ejemplo que inicie un flujo de OAuth 2.0

En este paso, crearemos un agente que inicie un flujo de autorización de OAuth 2.0 para que los tokens actúen en nombre del usuario. Para simplificar, el agente no realizará llamadas reales a servicios externos en nombre de un usuario, sino que nos demostrará que ha obtenido el consentimiento para actuar en nombre de nuestro usuario de prueba.

Código de agente

Cree un archivo con agentcoreidentityquickstart.py el nombre y guarde este código.

"""
AgentCore Identity Outbound Token Agent

This agent demonstrates the USER_FEDERATION OAuth 2.0 flow.

It handles the OAuth 2.0 user consent flow and inspects the resulting OAuth 2.0 access token.
"""

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.identity import requires_access_token
import asyncio
import jwt
import logging

app = BedrockAgentCoreApp()

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def decode_jwt(token):
    try:
        decoded = jwt.decode(token, options={"verify_signature": False})
        return decoded
    except Exception as e:
        return {"error": f"Error decoding JWT: {str(e)}"}

class StreamingQueue:
    def __init__(self):
        self.finished = False
        self.queue = asyncio.Queue()

    async def put(self, item):
        await self.queue.put(item)

    async def finish(self):
        self.finished = True
        await self.queue.put(None)

    async def stream(self):
        while True:
            item = await self.queue.get()
            if item is None and self.finished:
                break
            yield item

queue = StreamingQueue()

async def handle_auth_url(url):
    await queue.put(f"Authorization URL, please copy to your preferred browser: {url}")

@requires_access_token(
    provider_name="AgentCoreIdentityQuickStartProvider",
    scopes=["openid"],
    auth_flow="USER_FEDERATION",
    on_auth_url=handle_auth_url, # streams authorization URL to client
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding',
)
async def introspect_with_decorator(*, access_token: str):
    """Introspect token using decorator"""
    logger.info("Inside introspect_with_decorator - decorator succeeded")
    await queue.put({
        "message": "Successfully received an access token to act on behalf of your user!",
        "token_claims": decode_jwt(access_token),
        "token_length": len(access_token),
        "token_preview": f"{access_token[:50]}...{access_token[-10:]}"
    })
    await queue.finish()

@app.entrypoint
async def agent_invocation(payload, context):
    """Handler that uses only the decorator approach"""
    logger.info("Agent invocation started")

    # Start the agent task and immediately begin streaming
    task = asyncio.create_task(introspect_with_decorator())

    # Stream items as they come in
    async for item in queue.stream():
        yield item

    # Wait for task completion
    await task

if __name__ == "__main__":
    app.run()

Paso 4: Despliegue el agente en Runtime AgentCore

Alojaremos este agente en AgentCore Runtime. Podemos hacerlo fácilmente con la AgentCore CLI.

Desde su terminal, instale la AgentCore CLI y cree un proyecto de agente de Python Strands. Las opciones explícitas crean un agente basado en código en lugar de un arnés:

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --language Python --framework Strands \
  --model-provider Bedrock --memory none

Copie el script de su agente en el directorio de agentes del proyecto y sustituya al agente predeterminado:

cp agentcoreidentityquickstart.py IdentityQuickstart/app/IdentityQuickstart/main.py

Agregue la dependencia de JWT al proyecto generado:

cd IdentityQuickstart/app/IdentityQuickstart
uv add pyjwt
cd ../..

A continuación, despliega tu proyecto:

agentcore deploy

La CLI sintetiza una pila de AWS CDK e implementa su agente en Runtime. AgentCore Esto tarda aproximadamente de 2 a 3 minutos.

Actualice la política de IAM del agente para poder acceder a la bóveda de tokens y al secreto del cliente

La AgentCore CLI crea la función de ejecución del agente durante la implementación, pero la función no incluye automáticamente los permisos para acceder al almacén de fichas. Debes adjuntar una política adicional para permitir que el agente recupere los tokens de OAuth 2.0 en tiempo de ejecución.

Este script recupera tu cuenta y tu región de la AWS CLI, busca el rol de ejecución del agente en la CloudFormation pila y adjunta la política correspondiente. Puede copiar y pegar este script o guardarlo en un archivo y ejecutarlo.

#!/bin/bash

# Get account and region from AWS CLI
AWS_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)

# Get execution role from CloudFormation stack outputs
EXECUTION_ROLE=$(aws cloudformation describe-stack-resources \
  --stack-name AgentCore-IdentityQuickstart-prod \
  --query "StackResources[?ResourceType=='AWS::IAM::Role'].PhysicalResourceId" \
  --output text | head -1)

echo "Parsed values:"
echo "Execution Role: $EXECUTION_ROLE"
echo "Account: $AWS_ACCOUNT"
echo "Region: $REGION"

# Create the policy document with proper variable substitution
cat > agentcore-identity-policy.json << EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessTokenVault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetResourceOauth2Token",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": ["arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default/workload-identity/*",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default/oauth2credentialprovider/AgentCoreIdentityQuickStartProvider",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default",
        "arn:aws:secretsmanager:$REGION:$AWS_ACCOUNT:secret:bedrock-agentcore-identity!default/oauth2/AgentCoreIdentityQuickStartProvider*"
      ]
    }
  ]
}
EOF

# Create the policy
POLICY_ARN=$(aws iam create-policy \
    --policy-name AgentCoreIdentityQuickStartPolicy$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 4) \
    --policy-document file://agentcore-identity-policy.json \
    --query 'Policy.Arn' \
    --output text)

# Extract role name from ARN and attach policy
ROLE_NAME=$(echo $EXECUTION_ROLE | awk -F'/' '{print $NF}')
aws iam attach-role-policy \
    --role-name $ROLE_NAME \
    --policy-arn $POLICY_ARN

echo "Policy created and attached: $POLICY_ARN"

# Cleanup
rm agentcore-identity-policy.json

Paso 5: Invoca al agente

Ahora que todo está configurado, puede invocar al agente. Para esta demostración, utilizaremos el agentcore invoke comando y nuestras credenciales de IAM. Tendremos que pasar los --session-id argumentos --user-id y cuando usemos la autenticación de IAM.

agentcore invoke "TestPayload" --runtime IdentityQuickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed"

A continuación, el agente devolverá una URL a tu agentcore invoke comando. Copia y pega esa URL en tu navegador preferido y, a continuación, se te redirigirá a la página de inicio de sesión de tu servidor de autorización. El --user-id parámetro es el seudónimo que estás presentando a AgentCore Identity. El --session-id parámetro es el identificador de sesión, que debe tener al menos 33 caracteres.

Introduzca el nombre de usuario y la contraseña de su usuario en el servidor de autorización cuando se le pida en el navegador, o utilice el método de autenticación que prefiera que haya configurado. Si usó el script del paso 1 para crear una instancia de Cognito, puede recuperarlo del historial de su terminal.

Tu navegador debería redirigirte a la URL de devolución de llamada de OAuth2 configurada, que gestiona el flujo de enlace de la sesión. Asegúrese de que su servidor de devolución de llamadas de OAuth2 proporcione respuestas claras de éxito y error para indicar el estado de la autorización.

Debugging

Si detectas algún error o comportamiento inesperado, la salida del agente se captura en los CloudWatch registros de Amazon. Tras la ejecuciónagentcore deploy, se proporciona un comando de seguimiento de registros.

Limpieza

Cuando hayas terminado, ejecuta agentcore remove all y, a continuación, agentcore deploy desde el directorio de tu proyecto para desglosar los recursos de AgentCore Runtime desplegados. A continuación, elimine el grupo de usuarios de Amazon Cognito, separe y elimine la política de IAM que creó y elimine el proveedor de credenciales.

Prácticas recomendadas de seguridad

Al trabajar con información de identidad: