Federação com AWS

Nos dois sentidos, um JWT de identidade separado é seguido de uma troca de credenciais. Nenhum deles exige copiar uma chave de acesso de longa duração para o workload de destino.

Direção	Emissão do JWT de identidade	Troca
Basaltic → AWS	Endpoint de metadados da VM Basaltic ou API de tokens	`AssumeRoleWithWebIdentity` do AWS STS
AWS → Basaltic	`GetWebIdentityToken` do AWS STS	`AssumeRoleWithWebIdentity` do Basaltic

Basaltic para AWS

Você também pode usar uma sessão Basaltic autenticada de role ou service account. Chame a API de tokens com audience: "sts.amazonaws.com" e troque o JWT no AWS STS. Na política de confiança AWS abaixo, use o sujeito exato da role ou service account dessa prova. O fluxo de VM abaixo usa o endpoint de metadados e o helper guest. Você precisa de um administrador na conta AWS de destino, uma VM Basaltic com uma role anexada e o agente guest 1.15.11-1 ou posterior para renovar o arquivo automaticamente. A VM deve alcançar o AWS STS por HTTPS. A AWS deve alcançar os endpoints públicos de descoberta e JWKS do Basaltic.

Permitir que a VM solicite uma prova para AWS

Conceda à role Basaltic anexada iam:GetWebIdentityToken no próprio CRN, com a restrição basalt:IdentityTokenAudience = sts.amazonaws.com. Use o exemplo de política de identidade de VM e obtenha um token dentro da VM. Seu sujeito tem este formato imutável:

org:ORGANIZATION_UUID:account:ACCOUNT_UUID:instance:INSTANCE_UUID

Use os UUIDs reais da organização, conta e instância na política de confiança AWS. Não os substitua pelo nome da VM ou de uma role compartilhada.

Registrar o Basaltic na AWS

Na conta AWS de destino, registre o emissor https://iam.basaltic.sh com o client ID (audiência) sts.amazonaws.com. Um administrador pode executar:

aws iam create-open-id-connect-provider \
  --url https://iam.basaltic.sh \
  --client-id-list sts.amazonaws.com

Se o emissor já estiver registrado, reutilize o ARN do provedor e confirme que sua lista de client IDs inclui sts.amazonaws.com. Use a URL do emissor, não a URL do JWKS. A AWS obtém as chaves de verificação pelo documento de descoberta do Basaltic. Consulte a configuração de provedor OIDC na AWS. Crie uma role AWS com esta política de confiança, substituindo 123456789012 pelo ID da conta AWS de destino e o sujeito pelo sujeito exato da VM:

aws-trust.json

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::123456789012:oidc-provider/iam.basaltic.sh"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "iam.basaltic.sh:aud": "sts.amazonaws.com",
        "iam.basaltic.sh:sub": "org:ORGANIZATION_UUID:account:ACCOUNT_UUID:instance:INSTANCE_UUID"
      }
    }
  }]
}

aws iam create-role --role-name BasalticWorker \
  --assume-role-policy-document file://aws-trust.json

Anexe uma política de permissão AWS para os recursos específicos necessários à aplicação. A política de confiança permite a troca; ela não concede permissões de S3 ou de outros serviços. Mantenha a restrição de sujeito mesmo se várias roles ou contas Basaltic compartilharem o provedor.

Configurar o workload

Inicie o helper de arquivo de token como o usuário da aplicação. Com o exemplo systemd daquela página, configure o ambiente da aplicação:

export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/BasalticWorker
export AWS_WEB_IDENTITY_TOKEN_FILE=/run/basaltic-aws-identity/token
export AWS_ROLE_SESSION_NAME=basaltic-worker
export AWS_REGION=us-east-1
export AWS_EC2_METADATA_DISABLED=true

AWS_EC2_METADATA_DISABLED=true impede que um cliente AWS recorra ao endpoint de credenciais de metadados Basaltic, cujas credenciais são do Basaltic. Não configure chaves de acesso AWS estáticas nem outro perfil de credenciais nessa aplicação: eles podem ter precedência sobre o provedor de identidade web. A CLI AWS e os SDKs compatíveis trocam o JWT atual do arquivo e renovam as credenciais AWS quando necessário. O helper guest renova o arquivo independentemente. Verifique o suporte do provedor de credenciais assume-role do seu SDK.

aws sts get-caller-identity

O ARN retornado deve ser uma sessão de role assumida de BasalticWorker na sua conta AWS. Esse comando comprova qual identidade está em uso; teste também uma operação permitida da aplicação. Para inspecionar a troca diretamente sem uma credencial AWS existente:

umask 077
aws sts assume-role-with-web-identity --no-sign-request \
  --region us-east-1 \
  --role-arn arn:aws:iam::123456789012:role/BasalticWorker \
  --role-session-name basaltic-check \
  --web-identity-token file:///run/basaltic-aws-identity/token \
  --duration-seconds 900 > aws-session.json

Trate aws-session.json como uma credencial e exclua-o após o uso. A chave de acesso, a chave secreta e o token de sessão retornados são credenciais AWS. O Basaltic não os mantém nem os renova em nome da aplicação. As sessões AWS duram uma hora por padrão e podem durar de 900 segundos até o máximo da role. Elas podem durar mais que a prova Basaltic de cinco minutos. Remover a role Basaltic da VM impede novas provas; use os controles de revogação AWS para interromper sessões AWS já emitidas. Consulte o comportamento das sessões AWS STS.

AWS para Basaltic

A federação de saída da AWS transforma uma identidade AWS existente em um JWT assinado separado. Um workload EC2 usa as credenciais de seu perfil de instância para autenticar essa requisição. Outras credenciais AWS, incluindo uma role assumida ou sessão do IAM Identity Center, também podem autenticá-la quando permitido.

Habilitar a federação de saída AWS

Um administrador AWS habilita isso uma vez para a conta de origem:

aws iam enable-outbound-web-identity-federation
aws iam get-outbound-web-identity-federation-info

Registre o emissor específico da conta retornado em IssuerIdentifier. Ele se parece com https://ACCOUNT-SPECIFIC-ID.tokens.sts.global.api.aws. Não o substitua pelo endpoint comum da API STS. Consulte a configuração de federação de saída AWS. Conceda à role AWS de origem permissão para emitir provas para a audiência Basaltic. Esta política AWS permite apenas a audiência escolhida e no máximo cinco minutos:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:GetWebIdentityToken",
    "Resource": "*",
    "Condition": {
      "ForAllValues:StringEquals": {
        "sts:IdentityTokenAudience": "urn:example:basaltic:production"
      },
      "NumericLessThanEquals": {"sts:DurationSeconds": 300}
    }
  }]
}

Registrar o emissor AWS no Basaltic

Registre esse emissor exato na conta Basaltic que contém a role de destino.

Console
API
CLI

Abra IAM → OIDC providers → Create provider. Informe aws, o emissor específico da conta e urn:example:basaltic:production como audiência permitida.

POST https://iam.basaltic.sh/v1/oidc-providers
Authorization: Bearer YOUR_BASALTIC_ACCESS_TOKEN
X-Account-Id: production
Content-Type: application/json

{
  "name": "aws",
  "issuer": "https://ACCOUNT-SPECIFIC-ID.tokens.sts.global.api.aws",
  "audiences": ["urn:example:basaltic:production"]
}

basaltic iam oidc-provider create --account-id production \
  --name aws --issuer "$AWS_ISSUER" \
  --audiences urn:example:basaltic:production

Crie uma role Basaltic chamada aws-worker, anexe as políticas de permissão Basaltic necessárias e use esta política de confiança com o ARN real da role IAM AWS de origem:

{
  "principals": ["crn:iam::production:oidc-provider/aws"],
  "conditions": [
    {
      "operator": "equals",
      "key": "basalt:webidentity:Subject",
      "values": ["arn:aws:iam::123456789012:role/BasalticClient"]
    },
    {
      "operator": "equals",
      "set_operator": "for_any_value",
      "key": "basalt:webidentity:Audience",
      "values": ["urn:example:basaltic:production"]
    }
  ]
}

Use o ARN da role IAM presente no sub do JWT verificado, incluindo seu caminho. Ele difere do ARN STS arn:aws:sts::...:assumed-role/.../session retornado por GetCallerIdentity. Consulte os claims de token AWS.

Esta confiança identifica a role IAM AWS. Instâncias EC2 que compartilham essa role compartilham seu sujeito. O verificador OIDC genérico do Basaltic não mapeia claims EC2 personalizados da AWS para condições de confiança. Use uma role AWS dedicada quando workloads precisarem de acessos Basaltic separados; esta política não seleciona uma única instância EC2.

Emitir e trocar a partir da AWS

Use um endpoint regional do STS e uma versão da CLI AWS que inclua get-web-identity-token. Execute com a role AWS de origem:

umask 077
aws sts get-web-identity-token --region us-east-1 \
  --audience urn:example:basaltic:production \
  --signing-algorithm RS256 --duration-seconds 300 \
  --query WebIdentityToken --output text > aws-identity.jwt

jq -n --rawfile token aws-identity.jwt \
  '{role:"crn:iam::production:role/aws-worker",
    web_identity_token:($token | rtrimstr("\n")),
    session_name:"aws-workload", duration_seconds:900}' \
  > exchange.json

curl --fail --silent --show-error \
  -H 'Content-Type: application/json' --data-binary @exchange.json \
  https://iam.basaltic.sh/v1/assume-role-with-web-identity \
  > basaltic-session.json

rm -f aws-identity.jwt exchange.json

O Basaltic aceita tokens de identidade AWS RS256 e ES384. As provas AWS duram de 60 a 3600 segundos, com padrão de 300. O endpoint regional é obrigatório; o endpoint global do STS não atende essa operação de emissão. Consulte GetWebIdentityToken. Use o token bearer Basaltic retornado nas APIs ou suas credenciais temporárias de chave de acesso no S3 Basaltic. Emita e troque novamente antes de a sessão Basaltic expirar. Mantenha a resposta privada e remova-a quando a sessão não for mais necessária. Excluir o provedor Basaltic ou alterar suas audiências bloqueia novas trocas. Revogue as sessões Basaltic existentes separadamente. Desabilitar a federação de saída AWS é uma alteração para toda a conta; faça isso somente quando nenhuma outra integração precisar dela. JWTs de saída emitidos pela AWS não podem ser trocados de volta na AWS por AssumeRoleWithWebIdentity.

Diagnosticar o lado correto

Sintoma	Verifique
Metadados Basaltic retornam `401`	Obtenha um novo token IMDSv2 na mesma VM
Metadados Basaltic retornam `403`	Role anexada, `iam:GetWebIdentityToken`, condição de audiência e limite de permissão
A AWS informa `InvalidIdentityToken`	Use o JWT de identidade da VM e confira descoberta do emissor, JWKS, audiência e expiração
A troca AWS é negada	ARN do provedor e condições exatas de `aud`/`sub` na confiança da role AWS
A CLI AWS informa `FeatureDisabled`	Habilite a federação de saída na conta AWS de origem
O AWS `GetWebIdentityToken` é negado	Permissão da role AWS de origem e condições de audiência e duração
A troca Basaltic retorna `401`	Emissor AWS específico da conta, audiência do provedor e validade do JWT
A troca Basaltic retorna `403`	ARN da role IAM em `sub` e `for_any_value` na condição de audiência
Uma aplicação usa uma identidade AWS inesperada	Remova credenciais ou perfis estáticos com precedência e confira a configuração do arquivo de identidade web

Primeiros passos

Produtos

Plataforma

Ajuda

Federação com AWS

Basaltic para AWS

Permitir que a VM solicite uma prova para AWS

Registrar o Basaltic na AWS

Configurar o workload

AWS para Basaltic

Habilitar a federação de saída AWS

Registrar o emissor AWS no Basaltic

Emitir e trocar a partir da AWS

Diagnosticar o lado correto

​Basaltic para AWS

​Permitir que a VM solicite uma prova para AWS

​Registrar o Basaltic na AWS

​Configurar o workload

​AWS para Basaltic

​Habilitar a federação de saída AWS

​Registrar o emissor AWS no Basaltic

​Emitir e trocar a partir da AWS

​Diagnosticar o lado correto

Basaltic para AWS

Permitir que a VM solicite uma prova para AWS

Registrar o Basaltic na AWS

Configurar o workload

AWS para Basaltic

Habilitar a federação de saída AWS

Registrar o emissor AWS no Basaltic

Emitir e trocar a partir da AWS

Diagnosticar o lado correto