# Cree su primer agente autenticado
<a name="identity-getting-started-cognito"></a>

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.

**Topics**
+ [Requisitos previos](#identity-quick-start-prerequisites)
+ [Paso 1: Crear un grupo de usuarios de Cognito (opcional)](#identity-quick-start-cognito)
+ [Paso 2: Cree un proveedor de credenciales](#identity-quick-start-credential-provider)
+ [Paso 2.5: Agrega la URL de devolución de llamada a tu servidor de autorización de OAuth 2.0](#identity-update-credential-provider)
+ [Paso 3: Cree un agente de muestra que inicie un flujo de OAuth 2.0](#identity-quick-start-agent)
+ [Paso 4: implementar el agente en Runtime AgentCore](#identity-quick-start-deploy)
+ [Paso 5: Invoca al agente](#identity-quick-start-invoke)
+ [Limpieza](#identity-quick-start-cleanup)
+ [Prácticas recomendadas de seguridad](#identity-quick-start-security)

## Requisitos previos
<a name="identity-quick-start-prerequisites"></a>

Antes de comenzar, asegúrese de que dispone de lo siguiente:
+ Una AWS cuenta con los permisos adecuados
+ Python 3.10\+ instalado
+ La AWS CLI más reciente e `jq` instalada
+ Node.js Más de 18 instalados (para la AgentCore CLI)
+  AWS credenciales y región configuradas () `aws configure`

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
<a name="identity-quick-start-install"></a>

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)
<a name="identity-quick-start-cognito"></a>

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á:
+ Un grupo de usuarios de Cognito
+ Un cliente de OAuth 2.0 y un secreto de cliente para ese grupo de usuarios
+ Un usuario y una contraseña de prueba en ese grupo de usuarios de Cognito

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
<a name="identity-quick-start-credential-provider"></a>

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.

**Example**  

1. Si tiene un proyecto de AgentCore CLI, puede agregar el proveedor de credenciales mediante la CLI. La CLI creará el proveedor durante la implementación.

   ```
   agentcore add credential \
     --name AgentCoreIdentityQuickStartProvider \
     --type oauth \
     --discovery-url "$ISSUER_URL" \
     --client-id "$CLIENT_ID" \
     --client-secret "$CLIENT_SECRET"
   ```

   El proveedor de credenciales se creará cuando ejecute `agentcore deploy` el paso 4. Anote la URL de devolución de llamada del resultado de la implementación.

1. 

   ```
   #!/bin/bash
   # please note the expected ISSUER_URL format for Bedrock AgentCore is the full url, including .well-known/openid-configuration
   OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
     --name "AgentCoreIdentityQuickStartProvider" \
     --credential-provider-vendor "CustomOauth2" \
     --oauth2-provider-config-input '{
       "customOauth2ProviderConfig": {
         "oauthDiscovery": {
           "discoveryUrl": "'$ISSUER_URL'"
         },
         "clientId": "'$CLIENT_ID'",
         "clientSecret": "'$CLIENT_SECRET'"
       }
     }' \
     --output json)
   
   OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
   
   echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
   ```

## Paso 2.5: Agrega la URL de devolución de llamada a tu servidor de autorización de OAuth 2.0
<a name="identity-update-credential-provider"></a>

Para evitar redireccionamientos no autorizados, añade la URL de devolución de llamada recuperada desde [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)o hacia tu servidor de autorización de [GetOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetOauth2CredentialProvider.html)OAuth 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
<a name="identity-quick-start-agent"></a>

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
<a name="identity-quick-start-agent-code"></a>

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()
```

**nota**  
[Para ver un ejemplo de la implementación de un servidor de devolución de llamadas local para gestionar el [enlace de sesiones](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), consulte oauth2\_callback\_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) 

## Paso 4: implementar el agente en Runtime AgentCore
<a name="identity-quick-start-deploy"></a>

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
<a name="identity-quick-start-iam-policy"></a>

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
<a name="identity-quick-start-invoke"></a>

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.

**importante**  
El `--user-id` parámetro usa la ruta de la `GetWorkloadAccessTokenForUserId` API, que trata el UserID como una cadena opaca sin verificarlo con una identidad de usuario final autenticada. Esto es adecuado para escenarios de inicio rápido y desarrollo en los que no se dispone de un token de IdP. Para las implementaciones de producción en las que hay un JWT que identifica al usuario final, utilice en su lugar la ruta de JWT-based autenticación (`GetWorkloadAccessTokenForJWT`), que valida el emisor, la firma y el vencimiento del token. [Para obtener más información, consulte Obtener el token de acceso a la carga de trabajo.](get-workload-access-token.md)

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.](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html) 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.

**nota**  
Si interrumpe una invocación sin completar la autorización, es posible que deba solicitar una nueva URL con un nuevo ID de sesión (parámetro). `--session-id`

### Debugging
<a name="identity-quick-start-debugging"></a>

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

## Limpieza
<a name="identity-quick-start-cleanup"></a>

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
<a name="identity-quick-start-security"></a>

Al trabajar con información de identidad:

1.  **Nunca codifique las credenciales en su código** de agente

1.  **Utilice variables de entorno o Amazon SageMaker AI** para información confidencial

1.  **Aplique el principio de privilegios mínimos al** configurar los permisos de IAM

1.  **Cambie periódicamente las credenciales** de los servicios externos

1.  **Audite los registros de acceso** para monitorear la actividad de los agentes

1.  **Implemente una gestión adecuada de** los errores de autenticación