Conceitos básicos da federação de identidades de saída

Este guia mostra como habilitar a federação de identidades de saída para sua conta da AWS e obter seu primeiro JSON Web Token (JWT) (usando a API GetWebIdentityToken). Você habilitará o recurso, estabelecerá uma relação de confiança com um serviço externo, configurará as permissões do IAM e solicitará um token usando a AWS CLI ou o AWS SDK para Python (Boto3).

Pré-requisitos

Antes de começar, verifique se você tem:

Habilitar a federação de identidades de saída para sua conta

Você deve habilitar a federação de identidades de saída antes de solicitar tokens. Você pode habilitar o recurso usando o Console de Gerenciamento da AWS, ou programaticamente usando a API EnableOutboundWebIdentityFederation.

Usar a CLI do AWS

aws iam enable-outbound-web-identity-federation

Uso do AWS SDK para Python

import boto3

# Create IAM client
iam_client = boto3.client('iam')

# Enable outbound identity federation
response = iam_client.enable_outbound_web_identity_federation()
print(f"Feature enabled. Issuer URL: {response['IssuerUrl']}")
print(f"Status: {response['Status']}")

Usar o console AWS

Navegue até IAM e selecione Configurações da conta na seção Gerenciamento de acesso do menu de navegação à esquerda.

Depois de habilitar o recurso, anote o URL do emissor específico da sua conta. Você usará esse URL ao configurar relações de confiança em serviços externos. Você também pode recuperar esse URL do emissor, conforme necessário, usando a API GetOutboundWebIdentityFederationInfo.

Estabelecer uma relação de confiança no serviço externo

Configure o serviço externo para confiar e aceitar os tokens emitidos por sua conta da AWS. As etapas específicas variam de acordo com o serviço, mas geralmente envolvem:

Consulte a documentação do serviço externo para obter instruções detalhadas de configuração.

Configurar permissões do IAM

Crie uma política do IAM que conceda permissão para chamar a API GetWebIdentityToken e anexe a política a um perfil do IAM que precisa gerar tokens.

Este exemplo de política concede acesso à geração de tokens com restrições específicas. Ela permite solicitar tokens somente para “https://api.example.com” como público e aplica uma vida útil máxima do token de cinco minutos (300 segundos). Consulte Chaves de contexto de condição do IAM e do AWS STS para obter uma lista das chaves de condição que você pode usar para aplicar as propriedades do token.

Exemplo de política do IAM

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:GetWebIdentityToken",
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "sts:IdentityTokenAudience": "https://api.example.com"
                },
                "NumericLessThanEquals": {
                    "sts:DurationSeconds": 300
                }
            }
        }
    ]
}

Solicitar seu primeiro JSON Web Token (JWT)

Você pode solicitar um JSON Web Token usando a API GetWebIdentityToken. Você pode especificar os seguintes parâmetros ao chamar a API:

A API retorna os seguintes campos:

Usar a CLI do AWS

aws sts get-web-identity-token \
    --audience "https://api.example.com" \
    --signing-algorithm ES384 \
    --duration-seconds 300 \
    --tags Key=team,Value=data-engineering \
           Key=environment,Value=production \
           Key=cost-center,Value=analytics

Uso do AWS SDK para Python

import boto3

sts_client = boto3.client('sts')

response = sts_client.get_web_identity_token(
    Audience=['https://api.example.com'],
    DurationSeconds=300,
    SigningAlgorithm='RS256',
    Tags=[
        {'Key': 'team', 'Value': 'data-engineering'},
        {'Key': 'environment', 'Value': 'production'},
        {'Key': 'cost-center', 'Value': 'analytics'}
    ]
)

token = response['WebIdentityToken']

Você também pode decodificar o JWT para inspecionar seu conteúdo usando bibliotecas JWT padrão como PyJWT, Python-jose para Python, Nimbus JOSE+JWT para Java ou depuradores como jwt.io. Consulte Análise de reivindicações de tokens para obter mais informações sobre as reivindicações incluídas no token.

Usar o token com um serviço externo

Depois de receber o token, inclua-o nas solicitações para o serviço externo. O método varia de acordo com o serviço, mas a maioria dos serviços aceita tokens no cabeçalho de autorização. O serviço externo deve implementar uma lógica de validação de tokens que obtenha as chaves JWKS do endpoint conhecido do emissor, verifique a assinatura do token e valide as reivindicações essenciais antes de conceder acesso às suas workloads da AWS.

Obter chaves de verificação e metadados dos endpoints do OpenID Connect (OIDC)

O URL exclusivo do emissor da sua conta da AWS hospeda os endpoints de descoberta do OpenID Connect (OIDC) que contêm as chaves de verificação e os metadados necessários para a verificação do token.

O URL do endpoint de descoberta do OIDC contém metadados que alguns provedores usam para verificar os tokens. Está disponível em:

{issuer_url}/.well-known/openid-configuration

O endpoint do JWKS (JSON Web Key Set) contém as chaves usadas para verificar as assinaturas de tokens. Está disponível em:

{issuer_url}/.well-known/jwks.json

Obter o JWKS usando curl

curl https://{issuer_url}/.well-known/jwks.json

Resposta:

{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "ES384",
      "crv": "P-384",
      "x": "base64-encoded-x-coordinate",
      "y": "base64-encoded-y-coordinate"
    },
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-2",
      "n": "base64-encoded-modulus",
      "e": "AQAB"
    }
  ]
}

Uso do AWS SDK para Python

import requests

# Fetch Openid Configuration
open_id_config_response = requests.get("https://{issuer_url}/.well-known/openid-configuration")
open_id_config = open_id_config_response.json()

# Fetch JWKS
jwks_response = requests.get("https://{issuer_url}/.well-known/jwks.json")
jwks = jwks_response.json()

Recomendamos armazenar essas chaves em cache para evitar ter de obtê-las em cada verificação de token.

Validações essenciais de reivindicações

Sempre que possível, você deve validar reivindicações adicionais específicas da AWS para implementar um controle de acesso refinado em seu serviço externo. Por exemplo, valide a reivindicação org_id para restringir o acesso às entidades principais do IAM em sua organização da AWS, verifique principal_tags para aplicar o controle de acesso baseado em atributos (como permitir somente ambientes de produção ou equipes específicas) ou verifique as reivindicações de contexto de sessão, como lambda_source_function_arn ou ec2_instance_source_vpc, para restringir o acesso com base no recurso computacional. Consulte Análise das reivindicações de tokens para obter uma lista completa das reivindicações incluídas no token.