> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Federação com AWS

> Use a identidade de VM Basaltic na AWS e a identidade de workloads AWS no Basaltic, com credenciais temporárias nos dois sentidos.

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](https://docs.basaltic.sh/pt/iam/oidc.md#generate-a-token-through-the-api) 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](https://docs.basaltic.sh/pt/iam/vm-identity.md) e obtenha um token dentro da VM. Seu sujeito tem este formato imutável:

```text theme={null}
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:

> [tab] CLI
>
> ```bash theme={null}
> 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).

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:

```json aws-trust.json theme={null}
{
  "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"
      }
    }
  }]
}
```

> [tab] CLI
>
> ```bash theme={null}
> 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](https://docs.basaltic.sh/pt/iam/vm-identity.md#maintain-a-token-file) como o usuário da aplicação. Com o exemplo systemd daquela página, configure o ambiente da aplicação:

```bash theme={null}
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](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html) do seu SDK.

```bash theme={null}
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:

```bash theme={null}
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](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).

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

> [tab] CLI
>
> ```bash theme={null}
> 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_getting_started.html).

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:

```json theme={null}
{
  "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.

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

> [tab] API
>
> ```http theme={null}
> 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"]
> }
> ```

> [tab] CLI
>
> ```bash theme={null}
> 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:

```json theme={null}
{
  "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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_token_claims.html).

> [!WARNING]
>
> 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:

```bash theme={null}
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](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html).

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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.