View a markdown version of this page

Obtenha o token de acesso à carga de trabalho - Base da Amazônia 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 GetWorkloadAccessTokenForUserId API

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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, 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 os tokens de acesso à carga de trabalho diretamente, impedindo a extração e o uso indevido de tokens

  • Vinculação de identidade de usuário e agente — Os tokens contêm informações sobre a identidade do usuário e a identidade 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 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 invoca GetWorkloadAccessTokenForJWT com a identidade do usuário e a identidade da carga de trabalho do agente

  5. O Runtime passa o token de acesso à carga de trabalho para o código do agente como parte do cabeçalho da carga útil 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 verificada criptograficamente, e recuperações futuras 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 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 ID de usuário gerenciadas pelo cliente para o Identity AgentCore

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

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

Desvantagem: a plataforma trata o UserID 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 da carga de trabalho de chamada passar o ID de usuário correto e de as políticas do IAM terem o escopo adequado. Consulte Controles de segurança para GetWorkloadAccessTokenForUserId API 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 GetWorkloadAccessTokenForUserId API

A GetWorkloadAccessTokenForUserId API aceita uma string de identificador de usuário fornecida pelo chamador e emite um token de acesso à carga de trabalho com o escopo desse par de usuário-agente. Essa API foi projetada para oferecer suporte a clientes corporativos que precisam passar sequências 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 autenticada do usuário final. A vinculação de segurança depende inteiramente da carga de trabalho de chamada passar o ID de usuário correto e de suas políticas do IAM terem o escopo adequado. 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 de IAM apropriadasGetWorkloadAccessToken, incluindoGetWorkloadAccessTokenForUserId, e GetWorkloadAccessTokenForJWT

  • Escopo do token — Os tokens têm como escopo o par usuário-agente específico, 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 diferentes provedores. Por exemplo, use cognito+user123 e auth0+user123 diferencie 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 da 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 de carga de trabalho. Não o conceda de forma ampla por meio de políticas gerenciadas ou declarações de recursos curingas.

  • Negar 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 impedir que o caminho 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 do IAM autenticado e o valor do UserID que está sendo passado. Use AWS CloudTrail para monitorar GetWorkloadAccessTokenForUserId chamadas e detectar valores inesperados de ID de usuário.

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 tokens diretamente. Essa restrição ajuda a manter os limites de segurança e impede o acesso não autorizado ao token.

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 Diminuir o acesso aos provedores de credenciais por identidade da carga de trabalho.