Cree su primer agente autenticado

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

Al final de este tutorial, dispondrá de un agente completamente implementado que podrá autenticar a los usuarios a través de 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 tengas un servidor de autorización de OAuth 2.0. Si no tiene uno, en el paso 1 se 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 configurados, puede continuar con el paso 2. Este servidor de autorización actuará como proveedor de credenciales de recursos y representará a la autoridad que concede al agente un token de acceso saliente de OAuth 2.0.

Instala 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

Cree también el requirements.txt archivo con el siguiente contenido. La herramienta de AgentCore despliegue lo utilizará más adelante.

bedrock-agentcore
boto3
pyjwt
strands-agents

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

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

Al eliminar el grupo de usuarios de Cognito, también AgentCoreIdentityQuickStartPool 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: Cree un proveedor de credenciales

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

Si utilizas tu propio servidor de autorización, configura las variables ISSUER_URL de entorno y utiliza los valores correspondientes CLIENT_SECRET de tu 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 de la salida en su terminal para configurar las variables de entorno.

El código de su agente utilizará este proveedor de credenciales para obtener tokens de acceso que actúen en nombre de su usuario.

Paso 2.5: Agrega 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 desde CreateOauth2CredentialProvidero hacia tu servidor de autorización de GetOauth2CredentialProviderOAuth 2.0.

Si utiliza el script anterior para crear un servidor de autorización con Cognito, copie las sentencias EXPORT del resultado en su terminal para configurar las variables de entorno y actualice 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 muestra 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 obtener tokens que 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: implementar 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 nuevo proyecto:

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --defaults

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

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

Copie también el archivo de requisitos en el directorio de agentes para asegurarse de que todas las dependencias estén incluidas en la implementación:

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

A continuación, despliegue su proyecto:

cd IdentityQuickstart
agentcore deploy

La CLI sintetiza una pila de AWS CDK e implementa el 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 fichas 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 el acceso al almacén de fichas. Debes adjuntar una política adicional que permita al agente recuperar los tokens de OAuth 2.0 en tiempo de ejecución.

Este script recupera su cuenta y región de la AWS CLI, busca la función de ejecución del agente en la CloudFormation pila y adjunta la política adecuada. 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. Necesitaremos 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 su agentcore invoke comando. Copia y pega esa URL en tu navegador preferido y serás redirigido 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á presentando a AgentCore Identity. El --session-id parámetro es el ID 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 haya configurado de su preferencia. Si ha utilizado el script del paso 1 para crear una instancia de Cognito, puede recuperarlo del historial de su terminal.

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

Debugging

Si encuentra algún error o comportamiento inesperado, el resultado del agente se captura en CloudWatch los registros de Amazon. Tras la ejecuciónagentcore deploy, se proporciona un comando log tailing.

Limpieza

Cuando termines, ejecuta agentcore remove all y, a continuación, agentcore deploy desde el directorio de tu proyecto para eliminar 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: