Crie seu primeiro agente autenticado

Este tutorial de introdução explica como criar um agente autenticado completo desde o início usando o Amazon Bedrock AgentCore Identity e ajudará você a começar a implementar recursos de identidade em seus aplicativos de agente. Você aprenderá a configurar seu ambiente de desenvolvimento, criar uma infraestrutura de autenticação com o Cognito, implantar seu agente no AgentCore Runtime e testar todo o fluxo de trabalho de autenticação.

Ao final deste tutorial, você terá um agente totalmente implantado que pode autenticar usuários por meio de fluxos do OAuth2, obter tokens de acesso com segurança e demonstrar o ciclo de vida completo do gerenciamento de identidades. Seu agente será executado no AgentCore Runtime com as permissões adequadas do IAM, criando um ambiente de laboratório de teste onde você poderá demonstrar e testar os recursos de integração.

Pré-requisitos

Antes de começar, verifique se você tem:

Este tutorial exige que você tenha um servidor de autorização OAuth 2.0. Se você não tiver um, a Etapa 1 criará um para você usando grupos de usuários do Amazon Cognito. Se você tiver um servidor de autorização do OAuth 2.0 com um ID do cliente, segredo do cliente e um usuário configurado, você pode prosseguir para a etapa 2. Esse servidor de autorização atuará como um provedor de credenciais de recursos, representando a autoridade que concede ao agente um token de acesso OAuth 2.0 de saída.

Instale o SDK e as dependências

Crie uma pasta para este guia, crie um ambiente virtual do Python e instale o AgentCore SDK e o SDK do 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

Crie também o requirements.txt arquivo com o conteúdo a seguir. Isso será usado posteriormente pela ferramenta AgentCore de implantação.

bedrock-agentcore
boto3
pyjwt
strands-agents

Etapa 1: Criar um grupo de usuários do Cognito (opcional)

Este tutorial requer um servidor de autorização OAuth 2.0. Se você não tiver um disponível para teste ou se quiser manter seu teste separado do seu servidor de autorização, esse script usará suas AWS credenciais para configurar uma instância do Amazon Cognito para você usar como servidor de autorização. O script criará:

A exclusão do AgentCoreIdentityQuickStartPool grupo de usuários do Cognito também excluirá o client_id e o usuário associados.

Você pode escolher salvar esse script como create_cognito.sh e executá-lo na linha de comando ou colar o script na linha de comando.

#!/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'"

Etapa 2: criar um provedor de credenciais

Os provedores de credenciais são a forma como seu agente acessa os serviços externos. Crie um provedor de credenciais e configure-o com um cliente OAuth 2.0 para seu servidor de autorização.

Se você estiver usando seu próprio servidor de autorização, defina as variáveis ISSUER_URL de ambiente e CLIENT_SECRET com seus valores apropriados no seu servidor de autorização. CLIENT_ID Se você estiver usando o script anterior para criar um servidor de autorização para você com o Cognito, copie as instruções EXPORT da saída em seu terminal para definir as variáveis de ambiente.

Esse provedor de credenciais será usado pelo código do seu agente para obter tokens de acesso para agir em nome do seu usuário.

Etapa 2.5: Adicionar o URL de retorno de chamada ao seu servidor de autorização do OAuth 2.0

Para evitar redirecionamentos não autorizados, adicione a URL de retorno de chamada recuperada de CreateOauth2CredentialProviderou GetOauth2CredentialProviderpara seu servidor de autorização do OAuth 2.0.

Se você estiver usando o script anterior para criar um servidor de autorização com o Cognito, copie as instruções EXPORT da saída em seu terminal para definir as variáveis de ambiente e atualizar o cliente do grupo de usuários do Cognito com a URL de retorno de chamada do provedor de credenciais 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"

Etapa 3: criar um agente de amostra que inicie um fluxo do OAuth 2.0

Nesta etapa, criaremos um agente que inicia um fluxo de autorização do OAuth 2.0 para obter tokens para agir em nome do usuário. Para simplificar, o agente não fará chamadas reais para serviços externos em nome de um usuário, mas provará que obteve consentimento para agir em nome de nosso usuário de teste.

Código do agente

Crie um arquivo chamado agentcoreidentityquickstart.py e salve esse 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()

Etapa 4: implantar o agente no AgentCore Runtime

Hospedaremos esse agente no AgentCore Runtime. Podemos fazer isso facilmente com a AgentCore CLI.

No seu terminal, instale a AgentCore CLI e crie um novo projeto:

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

Copie seu script de agente no diretório de agentes do projeto, substituindo o agente padrão:

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

Além disso, copie seu arquivo de requisitos no diretório do agente para garantir que todas as dependências sejam incluídas na implantação:

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

Em seguida, implante seu projeto:

cd IdentityQuickstart
agentcore deploy

A CLI sintetiza uma pilha de AWS CDK e implanta seu agente no Runtime. AgentCore Isso leva aproximadamente de 2 a 3 minutos.

Atualize a política do IAM do agente para poder acessar o cofre de tokens e o segredo do cliente

A AgentCore CLI cria a função de execução do agente durante a implantação, mas a função não inclui automaticamente permissões para acesso ao cofre de tokens. Você precisa anexar uma política adicional para permitir que o agente recupere tokens do OAuth 2.0 em tempo de execução.

Esse script recupera sua conta e região da AWS CLI, encontra a função de execução do agente na pilha e CloudFormation anexa a política apropriada. Você pode copiar e colar esse script ou salvá-lo em um arquivo e executá-lo.

#!/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

Etapa 5: invocar o agente

Agora que tudo está configurado, você pode invocar o agente. Para esta demonstração, usaremos o agentcore invoke comando e nossas credenciais do IAM. Precisaremos passar os --session-id argumentos --user-id e ao usar a autenticação do IAM.

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

O agente então retornará uma URL para seu agentcore invoke comando. Copie e cole esse URL em seu navegador preferido e você será redirecionado para a página de login do seu servidor de autorização. O --user-id parâmetro é o ID do usuário que você está apresentando à AgentCore Identity. O --session-id parâmetro é o ID da sessão, que deve ter pelo menos 33 caracteres.

Insira o nome de usuário e a senha do usuário no servidor de autorização quando solicitado no navegador ou use o método de autenticação preferido que você configurou. Se você usou o script da Etapa 1 para criar uma instância do Cognito, poderá recuperá-lo do histórico do seu terminal.

Seu navegador deve redirecionar para o URL de retorno de chamada configurado do OAuth2, que gerencia o fluxo de vinculação da sessão. Certifique-se de que seu servidor de retorno de chamada OAuth2 forneça respostas claras de sucesso e erro para indicar o status da autorização.

Depuração

Se você encontrar algum erro ou comportamento inesperado, a saída do agente será capturada nos CloudWatch registros da Amazon. Um comando de rastreamento de log é fornecido após a execuçãoagentcore deploy.

Fazer a limpeza.

Depois de terminar, execute agentcore remove all e, em seguida, agentcore deploy a partir do diretório do projeto para eliminar os recursos do AgentCore Runtime implantados. Em seguida, exclua o grupo de usuários do Amazon Cognito, desanexe e exclua a política do IAM que você criou e exclua o provedor de credenciais.

Práticas recomendadas de segurança

Ao trabalhar com informações de identidade: