Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída

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 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, consultehttps://github.com/awslabs/amazon-bedrock-agentcore-samples/.

Para obter informações sobre como usar o OAuth com um servidor MCP, consulte Implantar servidores MCP no Runtime. AgentCore

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

Restrinja a invocação de entrada do IAM (SigV4) ao seu gateway

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.

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. 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"
                }
            }
        }
    ]
}

Exemplo de autorização de entrada JWT e acesso de saída OAuth

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:

Pré-requisitos

Antes de começar, você deve ter o seguinte:

Etapa 1: criar seu projeto de agente

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ê:

Isso gera:

Etapa 2: configurar AWS Grupo de usuários do Cognito e adição de um usuário

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.

Para configurar o grupo de usuários do Cognito e criar um usuário

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

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.

Se você quiser encarar esse tempo de execução, crie o gateway agora, antes de implantá-lo na próxima etapa. Depois de implantar, você adicionará o tempo de execução como destino do gateway.

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 gateway).

Etapa 4: implantar seu agente

{
    "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"
        }
    }
}

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.

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

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.

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"
    ]
}

Crie e implante o tempo de execução do agente

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.

Etapa 5: use o token do portador para invocar seu agente

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

{
    "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.

Respostas de erro do OAuth

OAuth-configured os agentes seguem os padrões de autenticação RFC 6749 (OAuth 2.0). 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), permitindo que os clientes descubram os endpoints do servidor de autorização por meio da API. GetRuntimeProtectedResourceMetadata

401 Não autorizado - Autenticação ausente

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.

Etapa 6: configurar seu agente para acessar as ferramentas usando o OAuth

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.

Etapa 6.1: Configurar provedores de credenciais

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

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

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=""))

O que acontece nos bastidores

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

Etapa 7: (opcional) propagar um token JWT para o Runtime AgentCore

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.

Etapa 7.1: Modifique o código do seu agente para ler os cabeçalhos

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

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

Etapa 7.3: Invoque seu agente

Invoque seu agente usando o OAuth e você deverá ver as reivindicações nos registros do seu agente em Logs. CloudWatch

Solução de problemas

Como depurar problemas relacionados ao token

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: