View a markdown version of this page

Obtenha o token de acesso à carga de trabalho - Amazon Bedrock AgentCore
O que é um token de acesso à carga de trabalho?Como o Runtime e o Gateway obtêm tokens automaticamenteComo recuperar manualmente os tokens de acesso à carga de trabalhoControles de segurança para GetWorkloadAccessTokenForUserIdAPI

Obtenha o token de acesso à carga de trabalho

Entender o que são tokens de acesso à carga de trabalho, como obtê-los e os aspectos de segurança de trabalhar com eles é essencial para criar aplicativos de agentes seguros. Esta seção aborda os principais conceitos e padrões de implementação que você precisa conhecer.

O que é um token de acesso à carga de trabalho?

Um token de acesso à carga de trabalho é um token AWS de acesso opaco assinado que permite que os agentes acessem AgentCore serviços primários, como provedores de credenciais de saída. O Runtime entrega automaticamente tokens de acesso à carga de trabalho às instâncias de execução do agente como cabeçalhos de carga útil, eliminando a necessidade de gerenciamento manual de tokens na maioria dos cenários.

Características principais

  • First-party somente serviços — Os tokens de acesso à carga de trabalho são exclusivamente para acessar AgentCore serviços AWS primários e não podem ser usados para serviços externos

  • Entrega automática — O Runtime e o Gateway fornecem automaticamente esses tokens aos agentes durante a execução

  • Segurança por design — as identidades dos Runtime-managed agentes não podem recuperar diretamente os tokens de acesso à carga de trabalho, evitando a extração e o uso indevido de tokens

  • Vinculação de identidade de usuário e agente — Os tokens contêm informações de identidade do usuário e do agente para acesso seguro às credenciais

Como o Runtime e o Gateway obtêm tokens automaticamente

Quando um agente é chamado por meio do AgentCore Runtime ou do Gateway com autenticação de entrada, o serviço processa automaticamente a geração do token de acesso à carga de trabalho:

  1. O Runtime valida o token OAuth do provedor de identidade de entrada (emissor, assinatura)

  2. O Runtime extrai as declarações do emissor e das subdeclarações do token OAuth que representa a identidade do usuário

  3. O Runtime busca a identidade da carga de trabalho associada ao agente

  4. O tempo de execução é invocado GetWorkloadAccessTokenForJWT com a identidade do usuário e a identidade da carga de trabalho do agente

  5. O tempo de execução passa o token de acesso à carga de trabalho para o código do agente como parte do cabeçalho da carga de invocação

Esse processo automático garante que os agentes recebam tokens com escopo adequado sem intervenção manual.

Como recuperar manualmente os tokens de acesso à carga de trabalho

Há dois padrões a serem usados para recuperar o token de acesso à carga de trabalho, dependendo de como você consegue identificar o usuário final do agente:

Padrão 1: JWT-based identificação (recomendado para produção)

Se o chamador do agente tiver um JWT emitido por um provedor de identidade para o usuário final, solicite um token de acesso à carga de trabalho usando. GetWorkloadAccessTokenForJWT Quando você fornece um JWT, o AgentCore Identity valida o token para garantir que ele esteja assinado corretamente e não tenha expirado, e usa suas declarações “iss” e “sub” para identificar o usuário de forma exclusiva. As credenciais armazenadas pelo agente em nome do usuário estão associadas a essa identidade criptograficamente verificada, e futuras recuperações exigem um token de acesso à carga de trabalho válido com a mesma identidade.

Use esse padrão quando:

  • Seu aplicativo se integra a um provedor de identidade (Cognito, Auth0, Okta etc.)

  • Você precisa de uma prova criptográfica da identidade do usuário final

  • Você está implantando na produção

Padrão 2: UserId-based identificação

Se o chamador do agente não tiver um JWT identificando o usuário final, solicite um token de acesso à carga de trabalho usando GetWorkloadAccessTokenForUserId uma string exclusiva identificando o usuário.

Use esse padrão quando:

  • Seu aplicativo gerencia seus próprios identificadores de usuário e você precisa passar cadeias de caracteres de UserID gerenciadas pelo cliente para Identity AgentCore

  • Você está em um cenário de desenvolvimento ou de início rápido em que um token de IdP ainda não está disponível

  • Sua arquitetura corporativa resolve a identidade do usuário a montante e passa um identificador confiável para a carga de trabalho do agente

Compensação: a plataforma trata o ID do usuário como uma string opaca e não pode verificá-lo em relação a uma identidade autenticada do usuário final. A vinculação de segurança depende de a carga de trabalho de chamada transmitir o ID de usuário correto e de as políticas do IAM terem um escopo adequado. Consulte Controles de segurança para GetWorkloadAccessTokenForUserIdAPI os controles recomendados.

Exemplos de código

Os exemplos abaixo ilustram o uso do AgentCore SDK para recuperar um token de acesso à carga de trabalho usando esses dois métodos:

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

Controles de segurança para GetWorkloadAccessTokenForUserIdAPI

A GetWorkloadAccessTokenForUserId API aceita uma string de identificação de usuário fornecida pelo chamador e emite um token de acesso à carga de trabalho com escopo definido para esse par de usuário-agente. Essa API foi projetada para oferecer suporte a clientes corporativos que precisam passar cadeias de caracteres de ID de usuário gerenciadas pelo cliente e criadores que não têm tokens de provedor de identidade (IdP) disponíveis durante o desenvolvimento.

Importante

Quando você usaGetWorkloadAccessTokenForUserId, a plataforma trata o userId valor como uma string opaca e não o verifica em relação a uma identidade de usuário final autenticada. A vinculação de segurança depende inteiramente da carga de trabalho de chamada que transmite o ID de usuário correto e do escopo adequado de suas políticas do IAM. Se seu aplicativo tiver acesso a um JWT identificando o usuário final, use GetWorkloadAccessTokenForJWT em vez disso, que valida o emissor, a assinatura e a expiração do token antes de emitir um token de acesso à carga de trabalho.

A GetWorkloadAccessTokenForUserId API implementa vários controles de segurança para impedir o acesso não autorizado:

  • Validação da identidade da carga de trabalho — A API verifica se a identidade solicitante tem permissão para agir em nome da identidade da carga de trabalho especificada

  • Service-managed restrição de identidade — Runtime-managed e as identidades da Gateway-managed carga de trabalho não podem recuperar tokens diretamente. Isso evita que os agentes extraiam tokens para uso indevido

  • Requisitos de permissão do IAM — Os chamadores devem ter as permissões apropriadas do IAMGetWorkloadAccessToken, incluindoGetWorkloadAccessTokenForUserId, e GetWorkloadAccessTokenForJWT

  • Escopo do token — Os tokens têm como escopo o par específico de usuário-agente, garantindo que as credenciais armazenadas em um usuário não possam ser acessadas por outro

  • Particionamento de ID de usuário para vários provedores de identidade — Ao usar vários provedores de identidade, particione seus IDs de usuário usando o padrão provider_id+user_id para evitar colisões de usuários entre provedores diferentes. Por exemplo, use cognito+user123 e auth0+user123 para distinguir usuários com o mesmo identificador em diferentes provedores de identidade

Controles de segurança recomendados

Como a plataforma não pode verificar a string UserID, você é responsável por garantir a integridade do valor passado para essa API. Aplique os seguintes controles:

  • Prefira GetWorkloadAccessTokenForJWT quando um JWT estiver disponível — O JWT-based caminho valida o emissor e a assinatura do token, fornecendo prova criptográfica da identidade do usuário. Use GetWorkloadAccessTokenForUserId somente quando um JWT não estiver disponível.

  • Derive o UserID de uma fonte confiável — O valor do UserId deve ser derivado do contexto do principal autenticado (por exemplo, identidade do chamador do IAM, atributos de sessão ou uma camada de resolução de identidade upstream) em vez de aceitar valores arbitrários fornecidos pelo cliente. Isso evita que um chamador autenticado se faça passar por outro usuário.

  • Restrinja a permissão do IAM — Somente diretores confiáveis devem ter a bedrock-agentcore:GetWorkloadAccessTokenForUserId permissão. Estabeleça o escopo dessa permissão para recursos específicos de identidade da carga de trabalho. Não o conceda amplamente por meio de políticas gerenciadas ou declarações de recursos curingas.

  • Negue GetWorkloadAccessTokenForUserId onde não for necessário — Para cargas de trabalho que sempre têm um JWT disponível, negue explicitamente a ação nas políticas do IAM para evitar que o caminho do UserID seja usado:

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • Implemente o registro de auditoria — registre a relação entre o principal autenticado do IAM e o valor do UserID que está sendo passado. Use AWS CloudTrail para monitorar GetWorkloadAccessTokenForUserId chamadas e detectar valores inesperados de UserID.

Se você encontrar o erro “WorkloadIdentity está vinculado a um serviço e não pode recuperar um token de acesso pelo chamador”, isso indica que a identidade da carga de trabalho é gerenciada pelo Runtime ou pelo Gateway e não pode recuperar os tokens diretamente. Essa restrição ajuda a manter os limites de segurança e impede o acesso não autorizado a tokens.

Para obter controles de segurança adicionais, você pode implementar políticas de acesso refinadas para restringir quais identidades de carga de trabalho podem acessar provedores de credenciais específicos. Para obter mais informações, consulte Reduzir o acesso aos provedores de credenciais por identidade da carga de trabalho.