O problema: infraestrutura de consentimento OAuth que cada equipe precisava construir do zero
Agentes de IA frequentemente precisam acessar serviços externos — como GitHub e Slack — em nome de um usuário real. Para isso, o usuário precisa se autenticar com o provedor e aprovar explicitamente os acessos solicitados. O sistema, por sua vez, precisa associar com segurança essa autorização ao usuário que a concedeu. Esse processo é chamado de vinculação de sessão (session binding).
Até recentemente, quem usava o fluxo OAuth de três pernas (3LO) — também conhecido como fluxo de código de autorização do OAuth 2.0 — dentro do AgentCore Identity precisava construir e hospedar toda essa infraestrutura por conta própria. Isso incluía exibir a URL de autorização, hospedar um callback HTTPS público, autenticar o usuário de retorno, gerenciar sessões de navegador e chamar o endpoint CompleteResourceTokenAuth para concluir o fluxo.
A AWS anunciou uma solução gerenciada para esse problema: o Consent Portal, uma experiência web integrada ao AgentCore Identity, que elimina a necessidade de construir essa infraestrutura manualmente.
O que é o Consent Portal e como ele funciona
O Consent Portal é uma interface web gerenciada e um endpoint de vinculação de sessão para o AgentCore Gateway. O administrador cria um portal associado a um gateway e compartilha a URL com os usuários. A partir daí, o fluxo é completamente gerenciado:
- O usuário se autentica com o Provedor de Identidade (IdP) da organização.
- O portal lista os serviços disponíveis para o agente e seus respectivos status de conexão.
- O usuário concede consentimento individualmente para cada provedor (por exemplo, GitHub ou Slack).
- O portal gerencia os redirecionamentos do navegador e a vinculação de sessão.
- O AgentCore Identity armazena os tokens resultantes em seu cofre de tokens.
Essa funcionalidade é especialmente útil para agentes acessados via Ambiente de Desenvolvimento Integrado (IDE) e clientes do Protocolo de Contexto de Modelo (MCP), como Kiro, Claude Code, Cursor e Visual Studio Code. O usuário concede o consentimento antes de invocar uma ferramenta, e as chamadas subsequentes já usam o token armazenado para aquele usuário.
Cenário de exemplo: assistente de desenvolvimento com acesso ao GitHub e Slack
Para ilustrar o funcionamento, a AWS usa o exemplo de uma empresa fictícia chamada Example Corp, que fornece aos seus desenvolvedores um assistente de codificação com IA via AgentCore Gateway. O assistente possui dois alvos configurados:
- Um alvo GitHub, capaz de listar repositórios e criar issues.
- Um alvo Slack, capaz de listar canais públicos e postar mensagens.
A empresa usa seu IdP corporativo para autenticar funcionários. O objetivo é que cada autorização OAuth do GitHub e do Slack fique vinculada ao funcionário que a aprovou, e que os desenvolvedores possam conectar cada provedor de forma independente, sem precisar repetir o processo toda vez que voltam à IDE.
Pré-requisitos
Antes de iniciar a configuração, são necessários:
- Uma conta AWS com acesso ao Amazon Bedrock AgentCore.
- Um AgentCore Gateway configurado com autorização de entrada JWT.
- Uma IDE ou cliente MCP configurado para se conectar ao mesmo AgentCore Gateway que será vinculado ao Consent Portal.
- Acesso administrativo ao IdP corporativo.
- Um OAuth App do GitHub e um aplicativo Slack registrados para um workspace de desenvolvimento ou teste.
- Permissão para registrar a URL de callback do AgentCore Identity em cada aplicativo provedor.
Configuração pelo administrador (Passos 1 a 6)
Passo 1: Preparar o IdP corporativo e as conexões do gateway
O administrador precisa anexar uma política do Gerenciamento de Identidade e Acesso (IAM) à sua identidade para executar os passos iniciais. A política cobre ações como criar o Consent Portal, gerenciar provedores de credenciais OAuth2, listar e atualizar alvos do gateway, e criar e repassar a role de execução. O trecho abaixo mostra a política exata documentada pela AWS:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ManageConsentPortalResources",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateConsentPortal",
"bedrock-agentcore:GetConsentPortal",
"bedrock-agentcore:ListConsentPortals",
"bedrock-agentcore:CreateOauth2CredentialProvider",
"bedrock-agentcore:GetOauth2CredentialProvider",
"bedrock-agentcore:ListOauth2CredentialProviders",
"bedrock-agentcore:GetGateway",
"bedrock-agentcore:ListGateways",
"bedrock-agentcore:CreateGatewayTarget",
"bedrock-agentcore:GetGatewayTarget",
"bedrock-agentcore:ListGatewayTargets",
"bedrock-agentcore:UpdateGatewayTarget"
],
"Resource": "*"
},
{
"Sid": "CreateAndPassExecutionRole",
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:GetRole",
"iam:PutRolePolicy",
"iam:GetRolePolicy",
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/service-role/AmazonBedrockAgentCoreConsentPortal*"
}
]
}Passo 2: Configurar o aplicativo no IdP corporativo
No IdP corporativo, o administrador cria um aplicativo web OpenID Connect (OIDC) para o Consent Portal. É necessário habilitar o grant de código de autorização, gerar um client ID e um client secret, e configurar os escopos de login — no mínimo openid. O administrador também deve registrar a URL de descoberta OIDC, que o portal usa para localizar o endpoint de autorização, o endpoint de token e as chaves de assinatura.
Um ponto importante: o IdP precisa emitir um Token Web JSON (JWT) de acesso que o portal consiga validar. No caso do Okta, isso exige um servidor de autorização customizado com uma política de acesso adequada. No Auth0, pode ser necessário configurar um audience para que o IdP retorne um JWT assinado em vez de um token opaco.
Passo 3: Criar o provedor de credenciais do IdP
O portal lê o client ID e o client secret do IdP a partir de um provedor de credenciais OAuth2. No console do Amazon Bedrock AgentCore, em Build > Identity > Outbound Auth, o administrador adiciona um novo cliente OAuth com o nome, o client ID, o client secret e a configuração de descoberta OIDC do IdP corporativo.
Passo 4: Verificar os pré-requisitos de saída
Antes de criar o Consent Portal, é necessário confirmar que:
- Os aplicativos OAuth do GitHub e do Slack estão registrados, com seus client secrets armazenados no AWS Secrets Manager.
- O AgentCore Identity possui provedores de credenciais OAuth separados para GitHub e Slack, e a URL de callback gerada por cada um está registrada no respectivo aplicativo provedor.
- Os alvos do gateway para GitHub e Slack usam o grant de código de autorização, solicitam apenas os escopos necessários e estão com status Ready.
- A role de execução do Consent Portal consegue ler os secrets gerenciados pelo cliente referenciados pelos provedores de credenciais de saída.
Passo 5: Criar o Consent Portal
Na página de Identity do console, a seção Consent portals lista os portais existentes na conta e região. Para criar um novo portal, o administrador define um nome (de 1 a 50 caracteres, usando letras, números, hífens e underscores), uma descrição opcional de até 512 caracteres, e seleciona o gateway do assistente de desenvolvimento.
Vale destacar: o nome do gateway fica visível para os usuários finais no Consent Portal, então é importante escolher um nome claro e reconhecível. Além disso, cada gateway suporta apenas um Consent Portal, e o gateway não pode ser alterado após a criação.
Nas configurações de credenciais do IdP, o administrador seleciona o provedor OAuth2 criado no Passo 3 e mantém o escopo openid como obrigatório. Para as permissões, o console oferece a opção de criar automaticamente uma service role com as permissões necessárias.
Enquanto o portal está sendo provisionado, o Número de Recurso da Amazon (ARN) e a role de execução já ficam visíveis, mas a URL ainda não é atribuída. Quando o provisionamento termina, o status muda para Active e a URL do portal passa a aparecer no console, seguindo o padrão https://<gateway-name>.consent-portal.bedrock-agentcore.<region>.amazonaws.com.
Passo 6: Registrar as URLs de callback e compartilhar o portal
Com a URL do portal em mãos, o administrador precisa atualizar as configurações de callback em três lugares distintos:
- No aplicativo do IdP corporativo (Cognito, Okta, Auth0, etc.): substituir o callback temporário por
<portal-url>/callback. - Em cada alvo 3LO do gateway: definir a URL de retorno padrão como
<portal-url>/connect/callback. - Nos aplicativos GitHub e Slack: confirmar que a
callbackUrlgerada pelo AgentCore Identity já está registrada (isso deve ter sido feito no Passo 4).
Após validar tudo em um navegador, o administrador compartilha a URL do portal com a equipe de desenvolvimento por um canal de comunicação aprovado.
Experiência do usuário final (Passo 7)
Com a URL em mãos, o desenvolvedor acessa o portal no navegador, clica em Sign in e é redirecionado para o IdP corporativo. Após autenticar com as credenciais corporativas, o portal usa sua role de execução IAM para recuperar os alvos configurados no gateway e seus estados de conexão.
Na página de Conexões, o desenvolvedor vê os clientes OAuth do GitHub e do Slack com seus respectivos status. Ao clicar em Connect para o GitHub, o GitHub exibe os escopos e os acessos de organização solicitados pelo aplicativo OAuth para que o usuário os aprove.
Após o GitHub retornar o resultado da autorização, o portal conclui a vinculação de sessão e exibe o cliente OAuth e o alvo como Connected. O Slack, por sua vez, permanece como Not connected — demonstrando que os consentimentos são independentes para cada provedor.
Se o agente precisar do Slack, o desenvolvedor pode conectar esse provedor de forma análoga. Caso contrário, basta deixar desconectado até que seja necessário. Após conceder o acesso, o desenvolvedor retorna à IDE ou ao cliente MCP configurado para usar o mesmo AgentCore Gateway e executa normalmente as chamadas de ferramentas do GitHub ou Slack.
O que acontece por baixo dos panos
O fluxo técnico interno funciona da seguinte forma:
- O portal valida a resposta do IdP e estabelece uma sessão de navegador criptografada.
- Usando sua role de execução, o portal lista os alvos 3LO do gateway associado.
- Quando o usuário clica em Connect, o portal chama
GetResourceOauth2Tokene recebe uma URL de autorização e um URI de sessão. - Após o provedor retornar o código de autorização ao AgentCore Identity, o navegador é redirecionado para o endpoint gerenciado de vinculação de sessão do portal.
- O portal chama
CompleteResourceTokenAuthcom o contexto do usuário autenticado. - Quando o provedor retorna um refresh token, o AgentCore Identity o armazena e o usa automaticamente para obter novos access tokens após a expiração do token atual.
Caso nenhum refresh token válido esteja disponível — porque o provedor não emitiu um, ou ele expirou ou foi revogado — o usuário precisa retornar ao Consent Portal e reautorizar. A AWS recomenda configurar os provedores para emitir refresh tokens sempre que suportado: por exemplo, habilitando a expiração de tokens user-to-server no GitHub ou a rotação de tokens no Slack.
Na próxima vez que o desenvolvedor abrir o portal, os provedores já conectados continuam visíveis como conectados. Não é necessário aprovar novamente, a menos que o grant seja revogado, expire ou exija novo consentimento. O desenvolvedor também pode desconectar um provedor e reconectá-lo posteriormente.
Auditoria com AWS CloudTrail
O Amazon Bedrock AgentCore registra as operações de consentimento no AWS CloudTrail. Para auditar a atividade, basta filtrar o histórico de eventos pela fonte bedrock-agentcore.amazonaws.com e revisar os seguintes eventos:
GetResourceOauth2Token: quando o portal inicia a autorização OAuth para um provedor.CompleteResourceTokenAuth: quando a vinculação de sessão é concluída.GetWorkloadAccessTokenForJWT: quando o portal obtém acesso ao gateway para o usuário autenticado.
Um evento GetResourceOauth2Token identifica o provedor de credenciais, os escopos solicitados, o fluxo OAuth, a role de execução do portal e a região. Valores sensíveis de token e estado são ocultados. O exemplo abaixo mostra a estrutura do evento:
{
"eventSource": "bedrock-agentcore.amazonaws.com",
"eventName": "GetResourceOauth2Token",
"awsRegion": "ap-southeast-2",
"userIdentity": {
"type": "AssumedRole",
"arn": "arn:aws:sts::111122223333:assumed-role/AmazonBedrockAgentCoreConsentPortalDefaultServiceRole-example/consent-dashboard-example"
},
"requestParameters": {
"workloadIdentityToken": "HIDDEN_DUE_TO_SECURITY_REASONS",
"resourceCredentialProviderName": "gateway-demo-github",
"scopes": ["read:user", "repo"],
"oauth2Flow": "USER_FEDERATION",
"customState": "HIDDEN_DUE_TO_SECURITY_REASONS"
},
"resources": [
{
"accountId": "111122223333",
"type": "AWS::BedrockAgentCore::OAuth2CredentialProvider",
"ARN": "arn:aws:bedrock-agentcore:ap-southeast-2:111122223333:token-vault/default/oauth2credentialprovider/gateway-demo-github"
}
],
"managementEvent": true
}Em caso de falhas, os campos errorCode e errorMessage, combinados com o horário do evento, a role assumida, a região, o provedor de credenciais e os escopos solicitados, ajudam a identificar a causa.
Limpeza dos recursos
Quando os recursos não forem mais necessários, a AWS recomenda a seguinte ordem de remoção:
- Excluir o Consent Portal no console do Amazon Bedrock AgentCore.
- Remover as URLs de callback do portal no aplicativo do IdP corporativo e nos alvos do gateway.
- Excluir os alvos do gateway que referenciam os provedores de credenciais de saída.
- Excluir os provedores de credenciais OAuth de saída e o provedor de credenciais do IdP corporativo, se não estiverem sendo usados em outro lugar.
- Excluir a role de execução do portal, se nenhum outro recurso a utilizar.
Atenção: é necessário excluir o alvo do gateway antes de excluir seu provedor de credenciais de saída. Um provedor ainda referenciado por um alvo não pode ser excluído.
Exemplos e documentação adicional
Para exemplos completos usando Microsoft Entra ID e Okta, a AWS disponibilizou repositórios no GitHub com os seguintes materiais:
- Consent portal com alvos de fluxo de código de autorização
- Alvo do AgentCore Gateway usando o fluxo de código de autorização OAuth
Para saber mais, acesse a página do Amazon Bedrock AgentCore.
Fonte
Manage end-user OAuth consent for AI agents with Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/manage-end-user-oauth-consent-for-ai-agents-with-amazon-bedrock-agentcore/)
Leave a Reply