# Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída
<a name="runtime-oauth"></a>

[Esta seção mostra como implementar autenticação e autorização para o tempo de execução do seu agente usando tokens portadores OAuth e JWT com Identity. AgentCore ](identity.md) Você aprenderá a configurar grupos de usuários do Cognito, configurar o tempo de execução do agente para autenticação JWT (Autenticação de Entrada) e implementar o OAuth-based acesso a recursos de terceiros (Autenticação de saída).

Para obter um exemplo completo, consulte[https://github.com/awslabs/amazon-bedrock-agentcore-samples/](https://github.com/awslabs/amazon-bedrock-agentcore-samples/).

Para obter informações sobre como usar o OAuth com um servidor MCP, consulte [Implantar servidores MCP](runtime-mcp.md) no Runtime. AgentCore 

O tempo de AgentCore execução do Amazon Bedrock fornece dois mecanismos de autenticação para agentes hospedados:

 **Autenticação IAM SigV4**   
O mecanismo padrão de autenticação e autorização que funciona automaticamente sem configuração adicional, semelhante a outras AWS APIs.  
 **X-Amzn-Bedrock-AgentCore-Runtime-User-Id Cabeçalho**   
Se sua solução exigir que o agente hospedado recupere tokens OAuth em nome dos usuários finais (usando Authorization Code Grant), você poderá especificar o identificador do usuário incluindo o `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` cabeçalho em suas solicitações. Esse cabeçalho usa o `GetWorkloadAccessTokenForUserId` caminho internamente.  
A invocação InvokeAgentRuntime com o `X-Amzn-Bedrock-AgentCore-Runtime-User-Id header` exigirá uma nova ação do IAM:`bedrock-agentcore:InvokeAgentRuntimeForUser`, além da `bedrock-agentcore:InvokeAgentRuntime` ação existente.
 **Quando usar esse cabeçalho versus a autenticação do JWT Bearer Token**   
Esse cabeçalho foi projetado para os seguintes casos de uso:  
+  **Clientes corporativos com identificadores de usuário gerenciados pelo cliente —** Organizações que mantêm suas próprias cadeias de caracteres de identidade de usuário e precisam passá-las à AgentCore Identity para vinculação de credenciais.
+  **Cenários de desenvolvimento e início rápido** — criadores que ainda não têm um token de IdP disponível e precisam de um caminho rápido para testar fluxos de credenciais com escopo de usuário.

  Para implantações de produção em que você tem um provedor de identidade configurado, use a autenticação [JWT Bearer Token](#oauth-sample-overview) em vez disso. O JWT path (`GetWorkloadAccessTokenForJWT`) valida o emissor, a assinatura e a expiração do token, fornecendo prova criptográfica da identidade do usuário. O caminho do `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` cabeçalho não verifica o ID do usuário em relação a uma identidade autenticada do usuário final. Ele depende da carga de trabalho de chamada para transmitir o valor correto e de suas políticas do IAM para restringir quem pode fornecê-lo.

   **Melhores práticas de segurança para X-Amzn-Bedrock-AgentCore-Runtime-User-Id cabeçalho** 
**dica**  
Para obter uma visão consolidada de todas as recomendações de segurança do Runtime, consulte [Melhores práticas de segurança para o AgentCore Runtime](runtime-security-best-practices.md).

  Como AgentCore trata o valor do cabeçalho como um identificador opaco sem verificá-lo em relação a uma identidade autenticada, você deve aplicar os seguintes controles para manter o limite de segurança:
+  **Restrinja a permissão do IAM** — Somente diretores confiáveis devem ter a `bedrock-agentcore:InvokeAgentRuntimeForUser` permissão. Defina essa permissão para recursos de tempo de execução específicos usando condições de recursos do IAM. Não o conceda amplamente por meio de políticas gerenciadas ou declarações de recursos curingas.
+  **Derive o ID do usuário do principal autenticado** — O valor do ID do usuário deve ser derivado do contexto do principal autenticado (por exemplo, identidade do chamador do IAM ou declarações de token do usuário) em vez de aceitar valores arbitrários fornecidos pelo cliente. Isso impede que um usuário autenticado se faça passar por outro usuário especificando manualmente um diferente. `user-id`
+  **Implemente o registro de auditoria** — registre a relação entre o principal autenticado do IAM (do contexto SigV4) e o `user-id` valor que está sendo passado. Use AWS CloudTrail para monitorar `InvokeAgentRuntime` chamadas que incluem o `runtimeUserId` parâmetro.
+  **Negue o cabeçalho em contextos não confiáveis** — Para tempos de execução em que a delegação de ID de usuário não é necessária, negue explicitamente a `bedrock-agentcore:InvokeAgentRuntimeForUser` ação nas políticas do IAM para evitar que o cabeçalho seja aceito:

  ```
  {
     "Statement": [
        {
           "Sid": "DenyUserIdDelegation",
           "Effect": "Deny",
           "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
           "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
        }
     ]
  }
  ```

 **Autenticação de token JWT Bearer**   
Você pode configurar o tempo de execução do agente para aceitar tokens portadores do JWT fornecendo a configuração do autorizador durante a criação do agente.  
Essa configuração inclui:  
+ URL de descoberta - Uma string que deve corresponder ao padrão dos URLs `^.+/\.well-known/openid-configuration$` de descoberta do OpenID Connect
+ Públicos permitidos - Uma lista de públicos permitidos que serão validados em relação à reivindicação de auxílio no token JWT
+ Clientes permitidos - Uma lista de identificadores de clientes permitidos que serão validados em relação à declaração client\_id no token JWT
+ Escopos permitidos - Uma lista de escopos permitidos que serão validados em relação à declaração de escopo no token JWT. O campo de `allowedScopes` autorização será configurado como uma lista de sequências de caracteres.
+ Declarações personalizadas obrigatórias - Uma lista das reivindicações obrigatórias que serão validadas em relação ao nome e valor da declaração contidos no token JWT recebido. Para obter detalhes sobre a configuração do autorizador, consulte [Configurar o autorizador JWT de entrada](inbound-jwt-authorizer.md) 

**nota**  
Um AgentCore Runtime pode suportar a autenticação de entrada baseada em IAM SigV4 ou JWT Bearer Token, mas não ambas simultaneamente. Você sempre pode criar versões diferentes do seu AgentCore Runtime e configurá-las para diferentes tipos de autorização de entrada. Quando você cria um tempo de execução com o Amazon Bedrock AgentCore, uma identidade de carga de trabalho é criada automaticamente para seu tempo de execução com o serviço AgentCore Identity.

**Topics**
+ [Restrinja a invocação de entrada do IAM (SigV4) ao seu gateway](#runtime-restrict-iam-gateway)
+ [Exemplo de autorização de entrada JWT e acesso de saída OAuth](#oauth-sample-overview)
+ [Pré-requisitos](#oauth-prerequisites)
+ [Etapa 1: criar seu projeto de agente](#prepare-agent)
+ [Etapa 2: configurar AWS Grupo de usuários do Cognito e adição de um usuário](#setup-cognito)
+ [Etapa 3 (opcional): inicie seu tempo de execução com um AgentCore gateway](#runtime-front-with-gateway)
+ [Etapa 4: implantar seu agente](#deploy-agent)
+ [Etapa 5: use o token do portador para invocar seu agente](#oauth-invoke-agent)
+ [Respostas de erro do OAuth](#oauth-error-responses)
+ [Etapa 6: configurar seu agente para acessar as ferramentas usando o OAuth](#oauth-outbound-access)
+ [Etapa 7: (opcional) propagar um token JWT para o Runtime AgentCore](#oauth-propagate-jwt-token)
+ [Solução de problemas](#troubleshooting)

## Restrinja a invocação de entrada do IAM (SigV4) ao seu gateway
<a name="runtime-restrict-iam-gateway"></a>

Você pode usar um AgentCore gateway em seu AgentCore Runtime para que o gateway se torne o único ponto de entrada controlado para o tempo de execução, oferecendo autorização baseada em políticas, Amazon Bedrock Guardrails, interceptores de solicitações e respostas e observabilidade unificada, tudo aplicado fora do próprio ambiente do agente. Para obter a justificativa completa e como configurar isso, consulte [Enfrente seu tempo de execução com um AgentCore gateway](runtime-security-best-practices.md#security-bp-front-with-gateway).

Mas isso só é útil se os chamadores não conseguirem acessar o tempo de execução diretamente ignorando o gateway. Se seu tempo de execução usa a autorização de entrada padrão do IAM (SigV4), você pode restringir a invocação ao gateway para que o tráfego chegue ao tempo de execução somente por meio dele. Para conseguir isso, anexe uma política baseada em recursos ao tempo de execução que restringe a invocação à função de execução do seu gateway. O gateway assume sua função de serviço para assinar solicitações no tempo de execução, portanto, a função de gateway é a principal que invoca o tempo de execução. Permita essa função e adicione um explícito `Deny` para cada outro principal para que nenhuma outra identidade possa invocar o tempo de execução, mesmo com uma política permissiva baseada em identidade. Para obter mais informações sobre políticas baseadas em recursos em tempos de execução, consulte as políticas do [Amazon Resource-based Bedrock](resource-based-policies.md). AgentCore

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowOnlyGatewayRole",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
        },
        {
            "Sid": "DenyOtherPrincipals",
            "Effect": "Deny",
            "Principal": { "AWS": "*" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "Condition": {
                "ArnNotEquals": {
                    "aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
                }
            }
        }
    ]
}
```

**dica**  
Um explícito `Deny` sempre substitui qualquer política`Allow`, inclusive com base em identidade, na mesma conta. Ao digitar “`Deny`on”, você `aws:PrincipalArn` garante que somente a função de execução do gateway possa invocar o tempo de execução, independentemente de quais outras permissões existam em sua conta.

**Importante**  
Restringir o tempo de execução à função de execução do gateway é tão forte quanto os controles sobre quem pode assumir essa função. Qualquer principal que possa assumir a função de execução do gateway pode invocar o tempo de execução como se fosse o gateway. Bloqueie a função adicionando `aws:SourceArn` `aws:SourceAccount` condições à política de confiança **da função de execução do gateway** para que somente seu gateway possa assumi-la. A orientação de [prevenção do Confused Deputy](runtime-security-best-practices.md#security-bp-confused-deputy) mostra a mesma técnica aplicada à função de execução de um tempo de execução; aplique o mesmo padrão aqui, mas defina a política de confiança na função de execução do gateway e no escopo `aws:SourceArn` do ARN do gateway.

## Exemplo de autorização de entrada JWT e acesso de saída OAuth
<a name="oauth-sample-overview"></a>

Este guia mostra o processo de configuração do tempo de execução do agente para ser invocado com um token de acesso compatível com OAuth usando o formato JWT. O agente de amostra será autorizado usando tokens de acesso do AWS Cognito. Posteriormente, você também aprenderá como o código do agente pode buscar tokens do Google em nome do usuário para verificar o Google Drive e buscar conteúdo.

 **O que você aprenderá** 

Neste guia, você aprenderá como:
+ Configure o grupo de usuários do Cognito, adicione um usuário e obtenha um token de portador para o usuário
+ Configure o tempo de execução do seu agente para usar o grupo de usuários do Cognito para autorização
+ Configure seu código de agente para buscar tokens OAuth em nome do usuário para chamar ferramentas

## Pré-requisitos
<a name="oauth-prerequisites"></a>

Antes de começar, você deve ter o seguinte:
+ Uma AWS conta com as permissões apropriadas
+ Compreensão básica da programação em Python
+ Familiaridade com contêineres Docker (para implantação avançada)
+ Configure um agente básico com tempo de execução bem-sucedido
+ A AWS CLI mais recente e instalada `jq`
+ Compreensão básica da autorização do OAuth, principalmente tokens portadores do JWT, reivindicações e os vários fluxos de concessão

## Etapa 1: criar seu projeto de agente
<a name="prepare-agent"></a>

Use o `agentcore create` comando para configurar um projeto de agente esqueleto com a estrutura de sua escolha:

```
agentcore create
```

O comando solicitará que você:
+ Escolha uma estrutura (escolha Strands Agents para este tutorial)
+ Forneça um nome de projeto
+ Configurar opções adicionais

Isso gera:
+ Código do agente com sua estrutura selecionada
+  Arquivo de configuração `agentcore/agentcore.json`
+  `requirements.txt`com as dependências necessárias

**nota**  
O código do agente gerado servirá como base para a implementação da autenticação OAuth nas etapas a seguir.

## Etapa 2: configurar AWS Grupo de usuários do Cognito e adição de um usuário
<a name="setup-cognito"></a>

Para configurar um grupo de usuários do Cognito e criar um usuário, você usará um script de shell que automatiza o processo.

Para obter mais informações, consulte [Etapa 2: Importar módulos de identidade e autenticação](identity-getting-started-google.md#identity-getting-started-step2).

<a name="setup-cognito"></a> **Para configurar o grupo de usuários do Cognito e criar um usuário** 
+ Crie um arquivo chamado `setup_cognito.sh` com o seguinte conteúdo:

  ```
  #!/bin/bash
  
  # Create User Pool and capture Pool ID directly
  export POOL_ID=$(aws cognito-idp create-user-pool \
    --pool-name "MyUserPool" \
    --policies '{"PasswordPolicy":{"MinimumLength":8}}' \
    --region $REGION | jq -r '.UserPool.Id')
  
  # Create App Client and capture Client ID directly
  export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
    --user-pool-id $POOL_ID \
    --client-name "MyClient" \
    --no-generate-secret \
    --explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
    --region $REGION | jq -r '.UserPoolClient.ClientId')
  
  # Create User
  aws cognito-idp admin-create-user \
    --user-pool-id $POOL_ID \
    --username $USERNAME \
    --region $REGION \
    --message-action SUPPRESS > /dev/null
  
  # Set Permanent Password
  aws cognito-idp admin-set-user-password \
    --user-pool-id $POOL_ID \
    --username $USERNAME \
    --password $PASSWORD \
    --region $REGION \
    --permanent > /dev/null
  
  # Authenticate User and capture Access Token
  export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
    --client-id "$CLIENT_ID" \
    --auth-flow USER_PASSWORD_AUTH \
    --auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
    --region $REGION | jq -r '.AuthenticationResult.AccessToken')
  
  # Output the required values
  echo "Pool id: $POOL_ID"
  echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
  echo "Client ID: $CLIENT_ID"
  echo "Bearer Token: $BEARER_TOKEN"
  ```

  Abra uma janela de terminal e defina as seguintes variáveis de ambiente:
  +  {{REGION}}— a AWS região que você deseja usar
  +  {{USERNAME}}— o nome de usuário do novo usuário
  +  {{PASSWORD}}— a senha do novo usuário

    ```
    export REGION=us-east-1 // set your desired Region
    export USERNAME=USER NAME
    export PASSWORD=PASSWORD
    ```

    Na janela do terminal, execute o script:

    ```
    source setup_cognito.sh
    ```

    Observe a saída do script. Você precisará desses valores nas próximas etapas.

Esse script cria um grupo de usuários do Cognito, um cliente de grupo de usuários, adiciona um usuário e gera um token de portador para o usuário. Por padrão, o token é válido por 60 minutos.

## Etapa 3 (opcional): inicie seu tempo de execução com um AgentCore gateway
<a name="runtime-front-with-gateway"></a>

Você pode usar um AgentCore gateway em seu AgentCore Runtime para que o gateway se torne o único ponto de entrada controlado para o tempo de execução, oferecendo autorização baseada em políticas, Amazon Bedrock Guardrails, interceptores de solicitações e respostas e observabilidade unificada, tudo aplicado fora do próprio ambiente do agente. Para obter a justificativa completa e como configurar isso, consulte [Enfrente seu tempo de execução com um AgentCore gateway](runtime-security-best-practices.md#security-bp-front-with-gateway).

Se você quiser encarar esse tempo de execução, [crie o gateway](gateway-create.md) agora, antes de implantá-lo na próxima etapa. Depois de implantar, você [adicionará o tempo de execução como destino do gateway](gateway-target-http-runtime.md).

Para garantir que os chamadores não possam ignorar o gateway, restrinja o tempo de execução para aceitar invocações somente desse gateway. Você configura isso na próxima etapa, como parte do autorizador, usando `allowedWorkloadConfiguration` (consulte [permitidoWorkloadConfiguration: restringir a invocação ao seu](#deploy-agent-allowed-workload) gateway).

## Etapa 4: implantar seu agente
<a name="deploy-agent"></a>

**Importante**  
A partir **de 13 de outubro de 2025,** o Amazon Bedrock AgentCore usa uma Service-Linked função (SLR) para permissões de identidade de carga de trabalho em vez de exigir a configuração manual da política do IAM para novos agentes.  
Os detalhes da Service-Linked função:  
 **Nome**: `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity` 
 **Diretor de serviço:** `runtime-identity.bedrock-agentcore.amazonaws.com` 
 **Objetivo:** gerencia tokens de acesso à identidade da carga de trabalho e credenciais OAuth
Certifique-se de que a função que você usa para invocar as APIs de AgentCore controle tenha permissão para criar a Service-Linked função:  

```
{
    "Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
    "Effect": "Allow",
    "Action": "iam:CreateServiceLinkedRole",
    "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
    "Condition": {
        "StringEquals": {
            "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
        }
    }
}
```
 **Benefício**: a Service-Linked função fornece automaticamente as permissões necessárias para o acesso à identidade da carga de trabalho sem exigir a configuração manual da política.  
Para obter informações detalhadas sobre a função vinculada ao serviço, consulte Função vinculada ao [serviço de identidade](service-linked-roles.md#identity-service-linked-role).

Agora, você implantará seu agente com autorização do JWT usando o grupo de usuários do Cognito que você criou. Você precisará criar um agente com a configuração do autorizador. A tabela a seguir representa os vários parâmetros de configuração do autorizador e como os usamos para validar o token de entrada.


| configuração\_do\_autorizador | reivindicação em token decodificado | Observações | 
| --- | --- | --- | 
| url de descoberta → emissor | iss | O URL de descoberta deve apontar para um URL do emissor. Isso deve corresponder à afirmação iss no token decodificado. | 
| Clientes permitidos | client\_id | client\_id no token deve corresponder a um dos clientes permitidos especificados no autorizador | 
| Público permitido | aud | Um dos valores na reivindicação de aud do token deve corresponder a um dos públicos permitidos especificados no autorizador | 
| permitido WorkloadConfiguration |  `internal`  | Opcional. No lançamento, usado para permitir que somente seu AgentCore Gateway invoque o tempo de execução. Consulte [Restringir a invocação ao seu gateway](#deploy-agent-allowed-workload). | 

Se client\_id e aud forem fornecidos, o autorizador de tempo de execução do agente verificará ambos.

### permitidoWorkloadConfiguration: restrinja a invocação ao seu gateway
<a name="deploy-agent-allowed-workload"></a>

O `allowedWorkloadConfiguration` campo no `customJWTAuthorizer` restringe quais cargas de trabalho na cadeia de identidade da solicitação podem invocar o tempo de execução. Defina a carga de trabalho permitida em seu gateway para que o tempo de execução aceite uma solicitação somente quando sua cadeia de identidade incluir esse gateway. É assim que um tempo de execução do OAuth (JWT) impõe que o tráfego chegue somente pelo gateway que você configurou na Etapa 3.

Você fornece as cargas de trabalho permitidas usando um dos campos a seguir. Você pode especificar uma ou ambas — uma solicitação é aceita se sua cadeia de identidade corresponder a uma entrada em **qualquer um dos** campos, então você não precisa fornecer ambas.
+  **HostingEnvironments** — Uma lista de ambientes de hospedagem cujas cargas de trabalho podem invocar o destino. Cada entrada é um objeto com um`arn`. No lançamento, o único ambiente de hospedagem compatível é o AgentCore Gateway, portanto, cada um `arn` deve ser um ARN do AgentCore Gateway.
+  **WorkloadIdentities** — Uma lista de nomes de identidade de carga de trabalho que podem invocar o destino. O nome da identidade da carga de trabalho **não** é um ARN. É o segmento final do ARN de identidade da carga de trabalho do gateway, que você pode encontrar no campo `workloadIdentityDetails` da `GetGateway` resposta. Por exemplo, se `workloadIdentityDetails.workloadIdentityArn` for`arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity`, o nome da identidade da carga de trabalho será`my-gateway-workload-identity`.

O exemplo a seguir cria um tempo de execução do agente que restringe a invocação a um AgentCore gateway específico por seu ARN. Especificar `hostingEnvironments` sozinho é a maneira mais simples de permitir um gateway:

```
{
    "authorizerConfiguration": {
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
            "allowedClients": ["your-client-id"],
            "allowedWorkloadConfiguration": {
                "hostingEnvironments": [
                    {
                        "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
                    }
                ]
            }
        }
    }
}
```

Como alternativa, você pode identificar o gateway pelo nome de identidade da carga de trabalho ou especificar os dois campos. Quando ambos estão presentes, uma solicitação é permitida se corresponder a uma entrada em qualquer um dos campos. O `allowedWorkloadConfiguration` trecho a seguir permite dois gateways diferentes — um identificado pelo ARN e outro pelo nome da identidade da carga de trabalho:

```
"allowedWorkloadConfiguration": {
    "hostingEnvironments": [
        {
            "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
        }
    ],
    "workloadIdentities": [
        "my-gateway-2-workload-identity"
    ]
}
```

**nota**  
No lançamento, `allowedWorkloadConfiguration` é compatível somente com destinos de AgentCore tempo de execução, e as cargas de trabalho permitidas são AgentCore Gateways.

### Crie e implante o tempo de execução do agente
<a name="deploy-agent-create-deploy"></a>

Com a configuração do autorizador pronta, crie e implante o tempo de execução do agente. Os exemplos a seguir mostram como fazer isso com a AgentCore CLI ou o AWS SDK for Python (Boto3). Observe o ARN de tempo de execução do agente na saída — você precisará dele para invocar o agente na próxima etapa.

**Example**  
 **Para configurar e implantar seu agente**   

1. Crie seu projeto de agente com a AgentCore CLI:

   ```
   agentcore create
   ```

   Quando solicitado, escolha sua estrutura (escolha Strands Agents para este tutorial).

1. Implante seu agente:

   ```
   agentcore deploy
   ```

1. Observe o ARN do tempo de execução do agente na saída. Você precisará disso na próxima etapa.
**dica**  
Você também pode executar o `agentcore create` comando sem sinalizadores para uma experiência totalmente interativa que orienta você na configuração do projeto.

1. 

   ```
   import boto3
   
   # Create the client
   client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")
   
   # Call the CreateAgentRuntime operation
   response = client.create_agent_runtime(
       agentRuntimeName='HelloAgent',
       agentRuntimeArtifact={
           'containerConfiguration': {
               'containerUri': '111122223333.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
           }
       },
       authorizerConfiguration={
           "customJWTAuthorizer": {
               "discoveryUrl": 'COGNITO_DISCOVERY_URL',
               "allowedClients": ['COGNITO_CLIENT_ID']
           }
       },
       networkConfiguration={"networkMode":"PUBLIC"},
       roleArn='arn:aws:iam::111122223333:role/AgentRuntimeRole',
       lifecycleConfiguration={
           'idleRuntimeSessionTimeout': 300,  # 5 min, configurable
           'maxLifetime': 1800                # 30 minutes, configurable
       },
   )
   ```

## Etapa 5: use o token do portador para invocar seu agente
<a name="oauth-invoke-agent"></a>

Agora que seu agente foi implantado com autorização do JWT, você pode invocá-lo usando o token portador.

**nota**  
Se você iniciou seu tempo de execução com um gateway na [Etapa 3](#runtime-front-with-gateway), adicione o tempo de execução implantado como um destino de gateway antes de invocar — consulte [Destinos de tempo de AgentCore execução](gateway-target-http-runtime.md) — e, em seguida, invoque por meio do endpoint do gateway mostrado nos exemplos a seguir, em vez do endpoint de tempo de execução.

**Importante**  
 **Importante para os usuários existentes: os** agentes criados **antes de 13 de outubro de 2025** continuarão usando a função de execução do agente para obter permissões de identidade e **exigirão** que a política anterior seja anexada à função de execução do agente.  
 **Novos agentes**: para agentes criados **em ou após 13 de outubro de 2025,** essa política **não é necessária**, pois as permissões são gerenciadas automaticamente pela Service-Linked função.  

```
{
    "Sid": "GetAgentAccessToken",
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
        "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
    ],
    # point to the workload identity for the runtime; the workload identity can be found in
    # the GetAgentRuntime response and has your agent name in it.
    "Resource": [
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
    ]
}
```

 **Invocar o agente** 

Obtenha um token de portador para o usuário que você criou com o Amazon Cognito.

```
# use the password and other details used when you created the cognito user

export TOKEN=$(aws cognito-idp initiate-auth \
    --client-id "$CLIENT_ID" \
    --auth-flow USER_PASSWORD_AUTH \
    --auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
    --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
```

Prossiga com a invocação do agente com o restante das instruções a seguir.

Invoque o agente com o OAuth.

**Example**  

1. 

   ```
   // Invoke with OAuth token
   export PAYLOAD='{"prompt": "hello what is 1+1?"}'
   
   export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com"
   # If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL
   # export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}"
   
   export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT"
   # If you fronted the runtime with a gateway (Step 3), the preceding URL works but there is also a simpler alternative:
   # export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations"
   
   curl -v -X POST "${INVOKE_URL}" \
   -H "Authorization: Bearer ${TOKEN}" \
   -H "X-Amzn-Trace-Id: your-trace-id" \
   -H "Content-Type: application/json" \
   -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: your-session-id" \
   -d ${PAYLOAD}
   ```

1. Como o boto3 não suporta invocação com tokens portadores, você precisará usar um cliente HTTP como a biblioteca de solicitações em Python.

   <a name="invoke-agent"></a> **Para invocar seu agente com um token de portador** 

1. Crie um script Python chamado `invoke_agent.py` com o seguinte conteúdo:

   ```
   import requests
   import urllib.parse
   import json
   import os
   
   # Configuration Constants
   REGION_NAME = "AWS_REGION"
   
   # === Agent Invocation Demo ===
   invoke_agent_arn = "YOUR_AGENT_ARN_HERE"
   auth_token = os.environ.get('TOKEN')
   print(f"Using Agent ARN from environment: {invoke_agent_arn}")
   
   # URL encode the agent ARN
   escaped_agent_arn = urllib.parse.quote(invoke_agent_arn, safe='')
   
   # Construct the URL — invoke the runtime directly
   url = f"https://bedrock-agentcore.{REGION_NAME}.amazonaws.com/runtimes/{escaped_agent_arn}/invocations?qualifier=DEFAULT"
   
   # If you are fronting the runtime with a gateway (see Step 3), invoke through
   # the gateway target instead (replace GATEWAY_ID and my-target):
   # url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations"
   
   # Set up headers
   headers = {
       "Authorization": f"Bearer {auth_token}",
       "X-Amzn-Trace-Id": "your-trace-id",
       "Content-Type": "application/json",
       "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "testsession123"
   }
   
   # Enable verbose logging for requests
   import logging
   logging.basicConfig(level=logging.DEBUG)
   logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)
   
   invoke_response = requests.post(
       url,
       headers=headers,
       data=json.dumps({"prompt": "Hello what is 1+1?"})
   )
   
   # Print response in a safe manner
   print(f"Status Code: {invoke_response.status_code}")
   print(f"Response Headers: {dict(invoke_response.headers)}")
   
   # Handle response based on status code
   if invoke_response.status_code == 200:
       response_data = invoke_response.json()
       print("Response JSON:")
       print(json.dumps(response_data, indent=2))
   elif invoke_response.status_code >= 400:
       print(f"Error Response ({invoke_response.status_code}):")
       error_data = invoke_response.json()
       print(json.dumps(error_data, indent=2))
   
   else:
       print(f"Unexpected status code: {invoke_response.status_code}")
       print("Response text:")
       print(invoke_response.text[:500])
   ```

1. {{AWS\_REGION}}Substitua pela AWS região que você está usando. da Etapa 3.

1. {{YOUR\_AGENT\_ARN\_HERE}}Substitua pelo ARN real de tempo de execução do agente da Etapa 3.

1. Execute o script :

   ```
   python invoke_agent.py
   ```

## Respostas de erro do OAuth
<a name="oauth-error-responses"></a>

OAuth-configured os agentes seguem os padrões de autenticação [RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Quando a autenticação está ausente, o serviço retorna uma resposta 401 não autorizada com um WWW-Authenticate cabeçalho (de acordo com a [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), permitindo que os clientes descubram os endpoints do servidor de autorização por meio da API. GetRuntimeProtectedResourceMetadata 

### 401 Não autorizado - Autenticação ausente
<a name="oauth-401-missing-authentication"></a>

Quando nenhum token de portador é fornecido no cabeçalho de autorização, a resposta é:

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

O `resource_metadata` URL no WWW-Authenticate cabeçalho aponta para a API de metadados de recursos protegidos (PRM). A API PRM permite que os clientes descubram quais servidores de autorização protegem esse agente e seus URLs de endpoint OAuth.

**nota**  
Você deve pré-registrar seu cliente OAuth no Cognito (via Console AWS ou CLI) para obter um antes de usar os endpoints descobertos. `client_id` O Amazon Cognito não é compatível com o Registro Dinâmico de Clientes (RFC 7591).

## Etapa 6: configurar seu agente para acessar as ferramentas usando o OAuth
<a name="oauth-outbound-access"></a>

Nesta seção, você aprenderá como conectar seu código de agente aos provedores de AgentCore credenciais para acesso seguro a recursos externos usando a autenticação OAuth2.

O exemplo a seguir demonstra como seu agente em execução no Agent Runtime pode solicitar o consentimento do OAuth dos usuários, permitindo que eles se autentiquem com a conta do Google e autorizem o agente a acessar o conteúdo do Google Drive.

Para obter mais informações sobre como configurar a identidade, consulte [Introdução à AgentCore identidade](identity-getting-started.md).

### Etapa 6.1: Configurar provedores de credenciais
<a name="setup-credential-providers"></a>

Para configurar um provedor de credenciais do Google, você precisa:

1. Registre seu aplicativo no Google para obter o ID e o segredo do cliente

1. Crie um provedor de credenciais OAuth usando a CLI. AWS Substitua {{your-client-id}} e {{your-client-secret}} por seu ID de cliente e segredo do cliente reais do Google OAuth2:

   ```
   OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
     --name "google-provider" \
     --credential-provider-vendor "GoogleOauth2" \
     --oauth2-provider-config-input '{
         "googleOauth2ProviderConfig": {
           "clientId": "your-client-id",
           "clientSecret": "your-client-secret"
         }
       }' \
   --output json)
   
   OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
   
   echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
   ```
**nota**  
Obtenha o `callbackUrl` da [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)resposta e adicione o URI à lista de URI de redirecionamento do seu aplicativo do Google. O URL de retorno de chamada deve ser semelhante a: https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/ \*\*\*\*\*\*\*\*-\*\*\*\*-\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

Certifique-se de que sua função de invocação tenha as permissões necessárias para acessar o provedor de credenciais.

### Etapa 6.2: permitir que o agente leia o conteúdo do Google Drive
<a name="enable-google-drive-access"></a>

Crie uma ferramenta com anotações do SDK principal do agente, conforme mostrado no exemplo a seguir, para iniciar automaticamente o processo OAuth de três etapas. Quando seu agente invoca essa ferramenta, os usuários serão solicitados a abrir o URL de autorização no navegador e conceder consentimento para que o agente acesse o Google Drive.

```
import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
    auth_flow="USER_FEDERATION", # 3LO flow
    on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
    print(access_token) #You can see the access_token
    # Make API calls...
    main(access_token)

asyncio.run(read_from_google_drive(access_token=""))
```

**nota**  
Para obter um exemplo de implementação de servidor de retorno de chamada local para lidar com a [vinculação de sessão](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), consulte [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) 

 **O que acontece nos bastidores** 

Quando esse código é executado, ocorre o seguinte processo:

1. O Agent Runtime autoriza o token de entrada de acordo com o autorizador configurado.

1. O Agent Runtime troca esse token por um token de acesso à carga de trabalho via `bedrock-agentcore:GetWorkloadAccessTokenForJWT` API e o entrega ao código do seu agente por meio do cabeçalho da carga útil. `WorkloadAccessToken`

1. Durante a invocação da ferramenta, seu agente usa esse token de acesso à carga de trabalho para chamar a API do Token Vault `bedrock-agentcore:GetResourceOauth2Token` e gerar uma URL de autenticação 3LO.

1. Seu agente envia essa URL para o aplicativo cliente conforme especificado no `on_auth_url` método.

1. O aplicativo cliente apresenta esse URL ao usuário, que autoriza o agente a acessar o Google Drive.

1. AgentCore O serviço de identidade recebe e armazena em cache com segurança o token de acesso do Google até que ele expire, permitindo que solicitações subsequentes do usuário usem esse token sem precisar que o usuário forneça consentimento para cada solicitação.

**nota**  
AgentCore O Identity Service armazena o token de acesso do Google no AgentCore Token Vault usando a identidade da carga de trabalho do agente e o ID do usuário (do token JWT de entrada, como o token Cognito) como chave vinculativa, eliminando solicitações de consentimento repetidas AWS até que o token do Google expire.

## Etapa 7: (opcional) propagar um token JWT para o Runtime AgentCore
<a name="oauth-propagate-jwt-token"></a>

Opcionalmente, você pode passar um cabeçalho de autorização para um AgentCore Runtime para extrair declarações. Isso pode ser feito usando a configuração da lista de permissões do cabeçalho da solicitação. Para obter mais informações, consulte [RequestHeaderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_RequestHeaderConfiguration.html).

### Etapa 7.1: Modifique o código do seu agente para ler os cabeçalhos
<a name="oauth-propagate-jwt-token-modify-code"></a>

Nesta etapa, você faz alterações no código do seu agente para poder decodificar e extrair declarações de um token JWT usando a biblioteca PyJWT.

 **requirements.txt** 

Adicione a dependência do PyJWT ao `requirements.txt` arquivo em seu projeto gerado.

```
PyJWT
```

 **Atualize seu código de agente** 

Modifique o arquivo do agente principal em seu projeto gerado (normalmente `src/main.py` ou similar, dependendo da sua escolha de estrutura) conforme mostrado no código a seguir. Você pode pular a validação da assinatura do token aqui, pois ela já foi validada pelo AgentCore Runtime quando a autorização de entrada foi concluída.

```
import jwt
import json
....

@app.entrypoint
def invoke(payload, context):
    auth_header = context.request_headers.get('Authorization')
    if not auth_header:
        return None

    # Remove "Bearer " prefix if present
    token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
    try:
        # Skip signature validation as agent runtime has validated the token already.
        claims = jwt.decode(token, options={"verify_signature": False})
        app.logger.info("Claims: %s", json.dumps(claims))
    except jwt.InvalidTokenError as e:
        app.logger.exception("Invalid JWT token: %s", e)

    .....
```

### Etapa 7.2: Criar o agente com a lista de permissões do cabeçalho da solicitação
<a name="oauth-propagate-jwt-token-create-agent"></a>

Use a AgentCore CLI para configurar o agente com a lista de permissões do cabeçalho da solicitação. Navegue até o diretório do projeto gerado e execute:

```
agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none

# Now deploy the agent runtime
agentcore deploy
```

**nota**  
A AgentCore CLI cria a estrutura do projeto e os arquivos de configuração. Ajuste a configuração do agente `agentcore/agentcore.json` conforme necessário para sua escolha de estrutura.

### Etapa 7.3: Invoque seu agente
<a name="oauth-propagate-jwt-token-invoke-agent"></a>

 [Invoque](#oauth-invoke-agent) seu agente usando o OAuth e você deverá ver as reivindicações nos registros do seu agente em Logs. CloudWatch 

## Solução de problemas
<a name="troubleshooting"></a>

### Como depurar problemas relacionados ao token
<a name="debug-token-issues"></a>

Se você encontrar problemas com a autenticação do token, poderá decodificar o token para inspecionar seu conteúdo:

```
echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i<l; i++) printf "="; print "" }' | base64 -D | jq
```

Isso produzirá a carga útil do token, que é semelhante a:

```
{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}
```

Ao solucionar problemas de token, verifique o seguinte:
+ O URL do emissor apontado pelo URL de descoberta no agente autorizador deve corresponder à reivindicação do emissor no token. Faça o seguinte para confirmar se eles coincidem:
  + Selecione o URL de descoberta que você forneceu na configuração do autorizador ao criar o agente, por exemplo: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_nnnnnnnnn/.well-known/openid-configuration` 
    + Verifique o URL do emissor -`"issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_12345566"`. Isso deve corresponder ao valor da declaração iss no token.
+  `client_id`a declaração no token deve corresponder a uma das entradas do autorizador AllowedClients, se fornecida
  + Anote o ID do cliente que você forneceu ao criar o agente
  + Confirme se isso corresponde à declaração client\_id no token decodificado
+  `aud`a reivindicação no token deve corresponder a uma das `allowedAudience` entradas do autorizador, se fornecida
  + Anote a lista de públicos que você forneceu quando criou o agente
  + Confirme se isso corresponde à `aud` afirmação no token decodificado
+ Os tokens são válidos apenas por alguns minutos (a expiração padrão do Amazon Cognito é de 60 minutos). Obtenha um novo token conforme necessário.