Primeiros Passos com Amazon Bedrock AgentCore Identity

Uma introdução prática ao AgentCore Identity: autentique usuários com JWT, aplique controle de acesso por função dentro do seu agente de IA e conecte-se com segurança a serviços externos como o Slack por meio do Token Vault.

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (9 articles)

1
Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
…
9
Primeiros Passos com Amazon Bedrock AgentCore Identity This article

Carlos Biagolini

AWS Solutions Architect

Published Oct 19, 2026

Last modified Oct 19, 2026

Introdução

Agentes de IA que acessam dados sensíveis precisam de controle de identidade e acesso. Um assistente voltado para clientes precisa saber quem está chamando para decidir quais informações revelar. Uma ferramenta interna precisa distinguir entre diferentes níveis de acesso dos funcionários. Sem autenticação, qualquer usuário poderia acessar qualquer dado, incluindo informações comerciais confidenciais.

O Amazon Bedrock AgentCore Identity fornece autenticação de entrada para agentes hospedados no AgentCore Runtime. Ele valida tokens JWT diretamente no endpoint do Runtime, rejeita requisições não autorizadas antes que elas cheguem ao seu código, e disponibiliza as claims do usuário (nome, email, grupos) para que o agente tome decisões de autorização refinadas.

Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Aqui, focamos em como usar o AgentCore Identity para implementar controle de acesso baseado em papéis (RBAC) para usuários do agente. Para um entendimento mais amplo do AgentCore e seus componentes, confira os outros artigos desta série:

Por Que AgentCore Runtime em Vez de Harness?

Em artigos anteriores, usamos o Harness (gerenciado, declarativo) para implantar nosso agente de concessionária de veículos. O Harness é ótimo para a maioria dos casos de uso, mas não dá acesso ao token JWT bruto. Não é possível escrever código personalizado que inspecione as claims do usuário e registre ferramentas condicionalmente.

Para autenticação de entrada com RBAC, precisamos do Runtime: trazemos nosso próprio container com código personalizado que lê o header Authorization, decodifica o token e decide quais ferramentas expor com base no grupo do chamador no Cognito. A plataforma valida o token (assinatura, expiração, audience, grupos) antes que ele chegue ao nosso código. Nós cuidamos apenas da lógica de negócio.

O Que Estamos Construindo

Estendemos o cenário da concessionária de veículos usados da série. O agente agora tem dois níveis de acesso:

Clientes podem pesquisar o inventário público de veículos (marca, modelo, ano, preço, quilometragem).
Funcionários podem fazer tudo que os clientes fazem, além de acessar dados internos de custo (custo de aquisição, custo de reparo, meta de margem).

O mecanismo de controle de acesso é deliberadamente direto: a sessão do agente para um cliente é construída sem a ferramenta de custos. Não existe nenhum caminho de código que possa vazar dados internos, independentemente de como o usuário formule a pergunta.

Arquitetura

A autorização acontece em duas camadas:

Camada da plataforma — O AgentCore Identity rejeita tokens que não possuem cognito:groups ∈ {customer, employee}.
Camada do agente — O código registra ferramentas condicionalmente com base no grupo. A ferramenta restrita simplesmente não existe para clientes.

Como o Token Chega ao Agente

Entender o fluxo da requisição é fundamental para fazer esta arquitetura funcionar:

O usuário se autentica com o Cognito e recebe um ID token — um JWT contendo cognito:groups, name, email e phone_number.
O frontend envia a requisição para o endpoint do AgentCore Runtime com o header Authorization: Bearer <id-token>.
O AgentCore Identity intercepta a requisição e valida o token: verifica a assinatura contra as chaves públicas do Cognito, confirma que a claim aud corresponde à audience permitida, e avalia a regra de custom_claim (pertencimento a grupo).
Se a validação passar, a plataforma remove o header Authorization por padrão — o container nunca o vê, a menos que você configure explicitamente o Request Header Allowlist para encaminhá-lo.
Com o allowlist configurado, o header Authorization chega ao código do agente. O agente decodifica o JWT (sem re-verificar a assinatura, já que a plataforma já fez isso) e lê cognito:groups para decidir quais ferramentas registrar.

Este último ponto é crítico: sem o Request Header Allowlist, o agente recebe a requisição mas não tem como saber quem é o chamador. Todos os usuários seriam tratados como clientes por padrão, independentemente do grupo real ao qual pertencem. O allowlist é o que conecta a autenticação no nível da plataforma com a autorização no nível da aplicação. Para mais detalhes sobre como headers customizados funcionam no AgentCore Runtime, veja Pass custom headers to Amazon Bedrock AgentCore Runtime .

Fluxograma mostrando o usuário autenticando com o Cognito e recebendo um ID token, o AgentCore Ident

Como É o ID Token

O ID token do Cognito é um JWT padrão com três partes (header.payload.signature). O payload é o que o agente lê após a decodificação. Aqui está um exemplo real da nossa usuária de demonstração Jane (funcionária):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "sub": "b4c844b8-e0e1-70da-7962-0f839370f537",
  "cognito:groups": ["employee"],
  "email_verified": true,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX",
  "cognito:username": "jane",
  "aud": "2bnnv2ng361p25ktnc1clc3ebo",
  "token_use": "id",
  "name": "Jane Doe",
  "phone_number": "+12025550102",
  "email": "jane.doe@example.com",
  "exp": 1785989421,
  "iat": 1785985821
}

Os campos que importam para nossa lógica de RBAC:

cognito:groups — Um array listando os grupos aos quais o usuário pertence. Este é o sinal de autorização. O agente verifica se "employee" está neste array para decidir se deve registrar a ferramenta restrita. O token de um cliente mostraria ["customer"] aqui.
aud — O App Client ID. O autorizador do AgentCore valida este campo contra allowed_audience para garantir que o token foi emitido para esta aplicação.
name, email, phone_number — Atributos de perfil que o agente usa para personalizar respostas (e que seriam necessários para notificações de escalação em um cenário de produção).
iss — A URL do emissor, que o autorizador resolve a partir da Discovery URL para buscar as chaves públicas para verificação de assinatura.

Você pode decodificar qualquer ID token colando-o em https://jwt.io ou executando JSON.parse(atob(token.split('.')[1])) no console do navegador.

Pré-requisitos

Conta AWS com permissões para criar recursos do Cognito, DynamoDB, ECR, IAM e AgentCore
AWS CLI configurado
Docker com buildx (para imagem ARM64)
Python 3 (para o proxy de teste local)
Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)
Acesso ao modelo habilitado para Amazon Nova 2 Lite no console do Bedrock

Step 1: Clonar o Repositório

O repositório complementar contém o código do agente, o frontend e scripts auxiliares que usaremos ao longo deste tutorial. Clone-o agora:

1
2
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreIdentity.git
cd PythonAwsBedrockAgentCoreIdentity

Usaremos as seguintes pastas nos próximos passos:

agent/ — Código-fonte da imagem do container (Step 4)
seed/ — Scripts para criar usuários e popular o DynamoDB (Steps 2 e 3)
frontend/ — Interface de chat no navegador para testes (Step 7)

Step 2: Criar o User Pool do Cognito

Precisamos de um provedor de identidade que emita tokens JWT com informação de pertencimento a grupos. O Cognito faz isso nativamente via a claim cognito:groups no ID token.

2.1 Criar o User Pool

2.1.1. Navegue até Amazon Cognito > User pools e clique em Create user pool.

Console do Amazon Cognito mostrando a página User pools com o botão Create user pool para iniciar o

2.1.2. Você verá a página "Set up resources for your application". Preencha da seguinte forma:

Define your application:

Application type: Selecione Single-page application (SPA). Isso cria o App Client sem client secret, que é o que precisamos para autenticação baseada em navegador.
Name your application: Digite agentcore-identity-demo.

Configure options:

Options for sign-in identifiers: Marque apenas Username (deixe Email e Phone number desmarcados).
Self-registration: Desmarque Enable self-registration (criaremos usuários manualmente via CLI).
Required attributes for sign-up: Selecione email, name e phone_number no dropdown.

Add a return URL:

Deixe o campo Return URL vazio (não estamos usando a hosted UI — nosso frontend autentica via API do Cognito diretamente).

2.1.3. Clique em Create user directory.

Página Set up resources for your application do Cognito preenchida com o tipo single-page applicatio

2.1.4. Uma página abrirá mostrando uma visão geral com exemplos de código para React, Angular e JavaScript. Role até o final e clique em Go to overview.

Após a criação, anote seu User Pool ID (mostrado no topo da página de detalhes do pool, formato: us-east-1_XXXXXXXXX).

2.2 Configurar o App Client

O passo "Create user directory" criou automaticamente um App Client (sem client secret, já que escolhemos SPA). Agora precisamos habilitar o fluxo USER_PASSWORD_AUTH, que é necessário para login programático a partir do frontend.

2.2.1. Clique no menu hambúrguer (☰) no canto superior esquerdo para expandir o painel de navegação. Em seguida, vá para App integration > App clients.

2.2.2. Clique no app client que foi criado (chamado agentcore-identity-demo).

Página App clients do Cognito mostrando o app client criado automaticamente selecionado para revisar

2.2.3. Clique em Edit na seção Authentication flows.

Detalhes do app client mostrando a seção Authentication flows com o botão Edit para alterar os fluxo

2.2.4. Habilite ALLOW_USER_PASSWORD_AUTH. Você verá outros fluxos já habilitados por padrão (ALLOW_USER_AUTH, ALLOW_USER_SRP_AUTH, ALLOW_REFRESH_TOKEN_AUTH) — mantenha-os como estão. Clique em Save changes.

Editor de fluxos de autenticação do app client com ALLOW_USER_PASSWORD_AUTH habilitado junto com os

2.2.5. Copie o Client ID (mostrado no topo da página do app client). Você também pode confirmar que o Client secret está vazio, o que significa que nenhum SECRET_HASH é necessário para autenticação — você precisará do Client ID mais tarde para o arquivo .env e para a configuração do autorizador do Runtime.

Página do app client destacando o valor do Client ID e o campo Client secret vazio, confirmando que

2.3 Criar Grupos

2.3.1. No painel de navegação esquerdo, clique em Groups, depois clique em Create group.

Página Groups do user pool do Cognito mostrando o botão Create group para adicionar os grupos custom

2.3.2. Crie os dois grupos, um de cada vez. Para cada grupo, preencha o Group name e clique em Create group:

Primeiro grupo: employee
Segundo grupo: customer

Formulário Create group do Cognito com o campo de nome do grupo, deixando precedence e IAM role vazi

Deixe Precedence e IAM role vazios para ambos os grupos. Veja o que eles fazem (não são necessários para esta demonstração):

Precedence — Uma prioridade numérica usada quando um usuário pertence a múltiplos grupos. O grupo com o menor número é considerado o grupo "preferido", e sua IAM role (se houver) é usada para a claim cognito:preferred_role. Como nosso agente lê todos os grupos do array, a precedência não afeta nossa lógica de RBAC. Veja GroupType API reference .
IAM role — Uma IAM role que o Cognito pode atribuir a usuários neste grupo quando eles se autenticam através de um Cognito Identity Pool (identidades federadas). Não estamos usando Identity Pools — nosso agente lê a claim cognito:groups diretamente do ID token e toma suas próprias decisões de autorização no código.

2.4 Criar Usuários de Demonstração

Crie três usuários via AWS CLI. Defina seu User Pool ID uma vez no início e depois execute os comandos:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# Set your User Pool ID here (from Step 1.1.4)
export POOL_ID=us-east-1_XXXXXXXXX

# Customer user
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username john \
  --user-attributes Name=name,Value="John Smith" Name=email,Value="john.smith@example.com" Name=email_verified,Value=true Name=phone_number,Value="+12025550101" Name=phone_number_verified,Value=true \
  --message-action SUPPRESS

aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username john \
  --password "Customer1Pass!" \
  --permanent

aws cognito-idp admin-add-user-to-group \
  --user-pool-id $POOL_ID \
  --username john \
  --group-name customer

# Employee user
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username jane \
  --user-attributes Name=name,Value="Jane Doe" Name=email,Value="jane.doe@example.com" Name=email_verified,Value=true Name=phone_number,Value="+12025550102" Name=phone_number_verified,Value=true \
  --message-action SUPPRESS

aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username jane \
  --password "Employee1Pass!" \
  --permanent

aws cognito-idp admin-add-user-to-group \
  --user-pool-id $POOL_ID \
  --username jane \
  --group-name employee

# User with no group (to test platform-level rejection)
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username alex \
  --user-attributes Name=name,Value="Alex Nobody" Name=email,Value="alex.nobody@example.com" Name=email_verified,Value=true Name=phone_number,Value="+12025550103" Name=phone_number_verified,Value=true \
  --message-action SUPPRESS

aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username alex \
  --password "NoGroup1Pass!" \
  --permanent

2.5 Anotar a Discovery URL

O autorizador JWT do AgentCore precisa da URL de descoberta OIDC para buscar as chaves públicas do Cognito e validar os tokens. Você pode encontrá-la na página Overview do User Pool, no campo OpenID Connect configuration URL.

A URL segue este padrão:

1
https://cognito-idp.<region>.amazonaws.com/<pool-id>/.well-known/openid-configuration

Você pode verificar que funciona colando a URL no seu navegador — ela deve retornar um documento JSON com issuer, jwks_uri e outros metadados OIDC.

Salve esta URL — você precisará dela no Step 5 ao criar o autorizador do AgentCore Runtime.

Step 3: Criar as Tabelas DynamoDB

Precisamos de duas tabelas: uma pública (veículos) e uma restrita (custos dos veículos).

3.1 Criar a Tabela de Veículos

3.1.1. Navegue até DynamoDB > Tables e clique em Create table.

3.1.2. Table name: agentcore-identity-vehicles

3.1.3. Partition key: vehicle_id (String)

3.1.4. Use as configurações padrão (capacidade on-demand). Clique em Create table.

Formulário Create table do Amazon DynamoDB para a tabela de veículos com a chave de partição vehicle

3.1.5. Após a tabela ser criada, clique nela para abrir seus detalhes. Vá para a aba Indexes e clique em Create index.

Detalhes da tabela do DynamoDB mostrando a aba Indexes e o botão Create index para adicionar um índi

3.1.6. Configure o Global Secondary Index:

Index name: body-type-index
Partition key: Digite body_type no campo Attribute, Data type String
Sort key: Deixe vazio
Index capacity: Mantenha os padrões (segue a tabela base — on-demand)
Warm throughput: Mantenha os valores padrão
Attribute projections: Selecione All (todos os atributos da tabela são projetados no índice)

Clique em Create index e aguarde o status ficar Active.

Formulário Create index do DynamoDB configurando o índice body type com a chave de partição body typ

3.2 Criar a Tabela de Custos dos Veículos

3.2.1. Crie outra tabela:

Table name: agentcore-identity-vehicle-costs
Partition key: vehicle_id (String)
Configurações padrão (on-demand)

Esta tabela não precisa de Global Secondary Index — o agente a consulta apenas por vehicle_id (a partition key).

3.3 Popular com Dados de Exemplo

A partir do repositório clonado, configure e execute os scripts de seed:

1
2
3
4
5
cd seed
cp .env.example .env
# Edit .env: set your POOL_ID and confirm the table names
./seed_users.sh
./seed_data.sh

Isso cria os 3 usuários de demonstração (com atribuições de grupo) e insere 8 veículos com seus respectivos registros internos de custo.

Step 4: Criar o Repositório ECR e Enviar a Imagem do Agente

Precisamos de um repositório ECR para armazenar a imagem de container do agente. O processo é o mesmo do artigo Getting Started with Amazon Bedrock AgentCore Harness and Runtime , usando o namespace agentcore/ para agrupar todos os repositórios relacionados a agentes.

4.1 Criar o Repositório

4.1.1. Navegue até Amazon ECR > Repositories e clique em Create repository.

4.1.2. Visibility: Private

4.1.3. Repository name: agentcore/identity-agent

4.1.4. Deixe todas as outras configurações nos valores padrão e clique em Create repository.

4.2 Build e Push da Imagem do Agente

A partir do repositório clonado:

1
2
3
4
5
6
7
8
9
10
11
12
cd agent

export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=<your-account-id>
export REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
export REPO_URI="${REGISTRY}/agentcore/identity-agent"

# Authenticate Docker with ECR
aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $REGISTRY

# Build ARM64 image and push
docker buildx build --platform linux/arm64 --tag ${REPO_URI}:latest --push .

Copie a URI completa da imagem (ex: 123456789012.dkr.ecr.us-east-1.amazonaws.com/agentcore-identity-agent:latest) — você precisará dela para a criação do Runtime.

Step 5: Criar a IAM Execution Role

O AgentCore Runtime precisa de uma role para puxar a imagem, escrever logs, invocar o modelo e ler o DynamoDB.

5.1 Criar a Role

5.1.1. Navegue até IAM > Roles e clique em Create role.

5.1.2. Trusted entity: Custom trust policy. Cole:

1
2
3
4
5
6
7
8
9
10
11
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
    "Condition": {
      "StringEquals": { "aws:SourceAccount": "<your-account-id>" }
    }
  }]
}

5.1.3. Nomeie como agentcore-identity-runtime-role.

5.2 Anexar Políticas

Após a criação, adicione uma inline policy com as seguintes permissões (substitua o account ID e a região):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECR",
      "Effect": "Allow",
      "Action": ["ecr:GetAuthorizationToken"],
      "Resource": "*"
    },
    {
      "Sid": "ECRImage",
      "Effect": "Allow",
      "Action": ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"],
      "Resource": "arn:aws:ecr:us-east-1:<account-id>:repository/agentcore/identity-agent"
    },
    {
      "Sid": "Logs",
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "logs:DescribeLogGroups"],
      "Resource": "arn:aws:logs:us-east-1:<account-id>:log-group:/aws/bedrock-agentcore/runtimes/*"
    },
    {
      "Sid": "XRay",
      "Effect": "Allow",
      "Action": ["xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets"],
      "Resource": "*"
    },
    {
      "Sid": "Metrics",
      "Effect": "Allow",
      "Action": ["cloudwatch:PutMetricData"],
      "Resource": "*",
      "Condition": { "StringEquals": { "cloudwatch:namespace": "bedrock-agentcore" } }
    },
    {
      "Sid": "BedrockNova",
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/amazon.nova-*",
        "arn:aws:bedrock:us-east-1:<account-id>:inference-profile/*amazon.nova-*"
      ]
    },
    {
      "Sid": "DynamoDB",
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem", "dynamodb:Query", "dynamodb:Scan"],
      "Resource": [
        "arn:aws:dynamodb:us-east-1:<account-id>:table/agentcore-identity-vehicles",
        "arn:aws:dynamodb:us-east-1:<account-id>:table/agentcore-identity-vehicles/index/*",
        "arn:aws:dynamodb:us-east-1:<account-id>:table/agentcore-identity-vehicle-costs"
      ]
    },
    {
      "Sid": "WorkloadIdentity",
      "Effect": "Allow",
      "Action": ["bedrock-agentcore:GetWorkloadAccessToken", "bedrock-agentcore:GetWorkloadAccessTokenForJWT"],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:<account-id>:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:us-east-1:<account-id>:workload-identity-directory/default/workload-identity/*"
      ]
    }
  ]
}

Nota: As permissões do Bedrock estão restritas a amazon.nova-* de propósito. Modelos de propriedade da Amazon são cobrados como uso nativo da AWS, enquanto modelos de terceiros (Anthropic, Meta) são cobrados pelo AWS Marketplace, que a maioria dos créditos promocionais não cobre.

Step 6: Criar o AgentCore Runtime

Este é o passo central — onde o AgentCore Identity é configurado.

6.1 Criar o Runtime

6.1.1. Navegue até Amazon Bedrock AgentCore > Runtime e clique em Create runtime.

Console do Amazon Bedrock AgentCore Runtime mostrando o botão Create runtime para iniciar a implanta

6.1.2. Runtime details:

Name: agentcore_identity_demo (apenas letras, números e underscores — sem hífens).

6.1.3. Agent source:

Source type: Selecione ECR Container.
Image URI: Cole a URI da sua imagem do Step 4 (ex: <your-account-id>.dkr.ecr.us-east-1.amazonaws.com/agentcore/identity-agent:latest).

6.1.4. Permissions:

IAM permissions: Selecione Use another role e escolha a role criada no Step 5 (ex: agentcore-identity-runtime-role).

6.1.5. Inbound Auth:

Protocol: Selecione HTTP.
Inbound Auth Type: Selecione Use JSON Web Tokens (JWT).
JWT schema configuration: Selecione Use existing Identity provider configurations.
Discovery URL: Cole sua URL OIDC do Cognito do Step 2.5.

6.1.6. JWT Authorization Configuration:

Marque Allowed audiences e insira seu Cognito App Client ID (do Step 2.2.5).
Desmarque Allowed clients (deixe vazio — ID tokens não carregam uma claim client_id, então habilitar isso rejeitaria toda requisição).
Desmarque Allowed scopes.
Marque Custom claims e configure: Name = cognito:groups, String type = String Array, Operator = Contains any, Value = customer,employee.
Desmarque Allowed gateways.

6.1.7. Additional configurations (VPC security):

VPC security: Selecione None (endpoint público).

6.1.8. Advanced configurations:

Security: Selecione Public.
Environment variables: Clique em Add new variable três vezes e adicione: VEHICLES_TABLE = agentcore-identity-vehicles, VEHICLE_COSTS_TABLE = agentcore-identity-vehicle-costs, BEDROCK_MODEL_ID = us.amazon.nova-2-lite-v1:0.
Lifecycle configurations: Mantenha os padrões (Session idle timeout: 15 minutes, Runtime lifecycle: 8 hours).

6.1.9. Clique em Create runtime e aguarde o status atingir Ready.

Formulário de criação do AgentCore Runtime mostrando a origem do contêiner no ECR, a role de execuçã

6.2 Configurar o Request Header Allowlist

Após o runtime ser criado, você precisa encaminhar o header Authorization para o container. Como explicado na seção de arquitetura, sem essa configuração o código do agente não consegue ler a identidade do chamador a partir do JWT — a plataforma remove o header após a validação.

Em agosto de 2026, durante o desenvolvimento deste POC, não encontramos esta opção na interface do console AWS. A documentação da AWS sobre headers customizados descreve como configurá-lo via AgentCore CLI (agentcore.json) ou AWS SDK (update_agent_runtime), mas não menciona uma configuração via console. Como isso pode mudar em futuras atualizações do console, verifique o link da documentação acima para as instruções mais recentes.

Para configurar via AWS CLI, execute o seguinte comando (substituindo os placeholders pelos seus valores dos passos anteriores):

1
2
3
4
5
6
7
8
9
aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id <your-runtime-id> \
  --role-arn arn:aws:iam::<your-account-id>:role/agentcore-identity-runtime-role \
  --agent-runtime-artifact '{"containerConfiguration":{"containerUri":"<your-image-uri>"}}' \
  --network-configuration '{"networkMode":"PUBLIC"}' \
  --authorizer-configuration '{"customJWTAuthorizer":{"discoveryUrl":"<your-discovery-url>","allowedAudience":["<your-client-id>"],"customClaims":[{"inboundTokenClaimName":"cognito:groups","inboundTokenClaimValueType":"STRING_ARRAY","authorizingClaimMatchValue":{"claimMatchValue":{"matchValueStringList":["customer","employee"]},"claimMatchOperator":"CONTAINS_ANY"}}]}}' \
  --request-header-configuration '{"requestHeaderAllowlist":["Authorization"]}' \
  --environment-variables '{"VEHICLES_TABLE":"agentcore-identity-vehicles","VEHICLE_COSTS_TABLE":"agentcore-identity-vehicle-costs","BEDROCK_MODEL_ID":"us.amazon.nova-2-lite-v1:0"}' \
  --region us-east-1

Importante: O comando update-agent-runtime é uma operação PUT completa. Você deve incluir todos os campos (role, artifact, network, authorizer, environment variables) mesmo que não tenham mudado. Omitir um campo irá resetá-lo para vazio.

Aguarde o status do runtime retornar a Ready:

1
2
3
4
aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <your-runtime-id> \
  --query "status" --output text \
  --region us-east-1

6.3 Copiar a URL de Invocação

A URL de invocação não é exibida diretamente no console. Você a constrói a partir do Runtime ARN (visível na página de detalhes do runtime em "Agent and tool details") usando este padrão:

1
https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations?qualifier=DEFAULT

Para codificar o ARN na URL, substitua : por %3A e / por %2F. Por exemplo, se seu ARN é:

1
arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/agentcore_identity_demo-XXXXXXXX

A URL de invocação fica:

1
https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aruntime%2Fagentcore_identity_demo-XXXXXXXX/invocations?qualifier=DEFAULT

Salve esta URL — ela vai no seu arquivo .env.

Step 7: Testar com o Frontend

7.1 Configurar o Frontend

A partir do repositório clonado:

1
2
cd frontend
cp .env.example .env

Edite o .env com os valores que você coletou:

1
2
3
INVOKE_URL=https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aruntime%2Fagentcore_identity_demo-XXXXXXXX/invocations?qualifier=DEFAULT
COGNITO_CLIENT_ID=your-client-id-from-step-1
AWS_REGION=us-east-1

7.2 Iniciar o Proxy

1
python3 proxy.py

Abra http://localhost:8080 no seu navegador.

7.3 Testar Cada Cenário

Faça login como john (customer, senha: Customer1Pass!)

Tente estas mensagens:

What SUVs do you have available under $30,000? → Deve listar veículos da tabela pública.
What was the acquisition cost of the Ford Explorer? → Deve recusar educadamente (a ferramenta não existe).

Chat do frontend mostrando o usuário cliente listando veículos disponíveis e sendo educadamente recu

Faça login como jane (employee, senha: Employee1Pass!)

Tente as mesmas mensagens para ver a diferença no comportamento:

What SUVs do you have available under $30,000? → Deve listar veículos (mesmo resultado que o cliente).
What was the acquisition cost of the Ford Explorer? → Deve retornar $21,000 e a meta de margem (funcionário tem acesso).

Chat do frontend mostrando o usuário funcionário listando veículos e recebendo o custo de aquisição

Faça login como alex (sem grupo, senha: NoGroup1Pass!)

Qualquer mensagem → Deve imediatamente mostrar Error 401: Authorization denied. A regra custom_claim no nível da plataforma rejeitou o token antes do container ser invocado.

Chat do frontend mostrando o usuário sem grupo recebendo a mensagem Error 401 Authorization denied p

Step 8: Limpeza

Para evitar cobranças contínuas, exclua os recursos nesta ordem:

AgentCore Runtime — Amazon Bedrock AgentCore > Runtime > selecione e exclua
Repositório ECR — Amazon ECR > Repositories > selecione e exclua (incluindo imagens)
Tabelas DynamoDB — DynamoDB > Tables > exclua ambas as tabelas
User Pool do Cognito — Amazon Cognito > User Pools > selecione e exclua
IAM Role — IAM > Roles > pesquise por agentcore-identity-runtime-role e exclua

Como o Código do Agente Funciona

O código do agente (agent/agent.py) implementa a lógica de RBAC. Veja o que acontece em cada requisição:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. Extract the JWT from the Authorization header (already validated by platform)
claims = jwt.decode(token, options={"verify_signature": False})

# 2. Resolve the caller's role from Cognito groups
groups = claims.get("cognito:groups", [])
is_employee = "employee" in groups

# 3. Register tools conditionally
tools = [search_vehicles]          # everyone gets this
if is_employee:
    tools.append(get_vehicle_costs)  # only employees get this

# 4. Build the agent with the appropriate tools
agent = Agent(model=model, system_prompt=prompt, tools=tools)

A ferramenta restrita (get_vehicle_costs) não é "negada quando chamada" — ela está ausente da sessão do cliente por completo. Não existe nenhum caminho de código que possa vazar dados internos, independentemente de tentativas de injeção de prompt.

Principais Conclusões

O AgentCore Identity valida tokens no nível da plataforma — assinatura, expiração, audience e custom claims são todos verificados antes do seu código executar. Requisições inválidas nunca chegam ao container.
custom_claim fornece defesa em profundidade — mesmo que o código do seu agente tivesse um bug, um usuário sem um grupo reconhecido ainda seria bloqueado no nível da plataforma.
O ID token carrega tudo — Grupos do Cognito (cognito:groups), nome de exibição, email e telefone estão todos no mesmo token. Nenhuma chamada extra de API é necessária.
allowed_audience (não allowed_clients) — ID tokens do Cognito carregam o client ID na claim aud, não client_id. Usar allowed_clients rejeitaria todo ID token.
request_header_allowlist é obrigatório — Sem adicionar Authorization ao allowlist, a plataforma remove o header após a validação e o agente não consegue ler as claims do usuário.
Amazon Nova mantém os custos previsíveis — Modelos first-party são cobrados como uso nativo da AWS (cobertos por créditos promocionais). Modelos de terceiros passam pelo AWS Marketplace.

Referências

Fique Conectado

Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:

LinkedIn: https://www.linkedin.com/in/biagolini
Medium: https://medium.com/@biagolini
GitHub: https://github.com/biagolini
YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini

Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.

Happy building on AWS! 🚀☁️

# ai # amazon-bedrock # amazon-bedrock-agentcore # amazon-bedrock-agents # agentic-ai

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (9 articles)

1
Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
…
9
Primeiros Passos com Amazon Bedrock AgentCore Identity This article

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.

Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article

Builder Center

Primeiros Passos com Amazon Bedrock AgentCore Identity

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (9 articles)

Carlos Biagolini

Introdução

Por Que AgentCore Runtime em Vez de Harness?

O Que Estamos Construindo

Arquitetura

Como o Token Chega ao Agente

Como É o ID Token

Pré-requisitos

Step 1: Clonar o Repositório

Step 2: Criar o User Pool do Cognito

2.1 Criar o User Pool

2.2 Configurar o App Client

2.3 Criar Grupos

2.4 Criar Usuários de Demonstração

2.5 Anotar a Discovery URL

Step 3: Criar as Tabelas DynamoDB

3.1 Criar a Tabela de Veículos

3.2 Criar a Tabela de Custos dos Veículos

3.3 Popular com Dados de Exemplo

Step 4: Criar o Repositório ECR e Enviar a Imagem do Agente

4.1 Criar o Repositório

4.2 Build e Push da Imagem do Agente

Step 5: Criar a IAM Execution Role

5.1 Criar a Role

5.2 Anexar Políticas

Step 6: Criar o AgentCore Runtime

6.1 Criar o Runtime

6.2 Configurar o Request Header Allowlist

6.3 Copiar a URL de Invocação

Step 7: Testar com o Frontend

7.1 Configurar o Frontend

7.2 Iniciar o Proxy

7.3 Testar Cada Cenário

Step 8: Limpeza

Como o Código do Agente Funciona

Principais Conclusões

Referências

Fique Conectado

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (9 articles)