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

# Tokens de identidade de VM

> Obtenha provas OIDC vinculadas à audiência de uma instância Basaltic e renove-as para serviços externos.

Uma VM Basaltic pode obter um JWT de identidade pelo serviço de metadados sem armazenar uma credencial de longa duração. Use-o com [AWS STS](https://docs.basaltic.sh/pt/iam/aws-federation.md) ou outro serviço que confie no emissor OIDC do Basaltic.

A VM precisa de uma [role IAM anexada](https://docs.basaltic.sh/pt/compute/instances.md#change-an-existing-instances-role). Suas políticas devem permitir `iam:GetWebIdentityToken` no CRN dessa role. Restrinja a audiência ao serviço de destino:

```json theme={null}
{
  "version": "2024-01-01",
  "statements": [{
    "effect": "allow",
    "actions": ["iam:GetWebIdentityToken"],
    "resources": ["crn:iam::production:role/aws-worker"],
    "conditions": [{
      "operator": "equals",
      "key": "basalt:IdentityTokenAudience",
      "values": ["sts.amazonaws.com"]
    }]
  }]
}
```

Aplique como [política inline ou anexada à role](https://docs.basaltic.sh/pt/iam/policies.md). Os limites de permissão da role também se aplicam. `basalt:IdentityTokenDurationSeconds` contém a duração solicitada em segundos, incluindo o padrão `300` quando a duração não é informada.

## Solicitar um token dentro da VM

Primeiro obtenha um token de sessão IMDSv2. Depois solicite um JWT de identidade com uma audiência externa:

```bash theme={null}
umask 077
IMDS_TOKEN=$(curl --fail --silent --show-error --noproxy '*' \
  -X PUT -H 'X-aws-ec2-metadata-token-ttl-seconds: 300' \
  http://169.254.169.254/latest/api/token)

curl --fail --silent --show-error --noproxy '*' \
  -H "X-aws-ec2-metadata-token: $IMDS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"audience":"sts.amazonaws.com","duration_seconds":300}' \
  http://169.254.169.254/latest/basaltic/iam/identity-token \
  > identity-response.json

jq -r .token identity-response.json > identity.jwt
rm -f identity-response.json
unset IMDS_TOKEN
```

A resposta JSON contém `token` e `expires_at`. A duração padrão é 300 segundos; você pode solicitar de 60 a 300 segundos. Requisições repetidas podem retornar um token em cache ainda válido, então use a expiração retornada. Toda requisição verifica as permissões atuais da role, inclusive quando usa o cache.

Este endpoint sempre exige IMDSv2, mesmo quando os metadados comuns permitem IMDSv1. Ele aceita apenas `audience` e o campo opcional `duration_seconds`. A plataforma fornece a identidade da VM; a requisição não pode escolher outra VM, conta, organização ou sujeito. A audiência `basaltic` é reservada para acesso à API e é rejeitada aqui.

Os três tokens envolvidos são diferentes:

| Token | Finalidade |
| - | - |
| Token de sessão IMDSv2 | Acesso ao serviço de metadados desta VM |
| JWT de identidade da VM | Prova apresentada a uma troca externa de credenciais |
| Token de acesso à API Basaltic | Chamadas às APIs Basaltic pela role anexada |

## Claims de identidade

O emissor é `https://iam.basaltic.sh`. Os JWTs usam ES256 e incluem `iss`, `sub`, `aud`, `iat`, `exp` e `jti`.

O sujeito é:

```text theme={null}
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:instance:INSTANCE_UUID
```

Use o sujeito exato na política de confiança do destino. Esses UUIDs são imutáveis. Renomear um recurso não altera sua identidade; recriar uma VM com o mesmo nome produz outro sujeito. Duas VMs que compartilham uma role Basaltic ainda têm sujeitos diferentes.

O destino deve verificar a assinatura com o [JWKS](https://docs.basaltic.sh/pt/iam/oidc.md#discovery-and-keys) descoberto do emissor antes de confiar nos claims. Decodificar um JWT sem verificá-lo é útil para inspecionar seu conteúdo, mas não comprova nada.

## Manter um arquivo de token

A versão `1.15.11-1` ou posterior do agente guest inclui o comando `identity-token`. Atualize `basaltic-guest-agent` pelo repositório de pacotes Basaltic configurado na VM antes de usá-lo.

Execute o helper com o mesmo usuário da aplicação, usando um diretório de saída privado. Ele renova a prova antes da expiração e substitui atomicamente um arquivo com modo 0600:

```bash theme={null}
install -d -m 0700 "$HOME/.local/run/basaltic"
basaltic-guest-agent identity-token \
  --audience sts.amazonaws.com \
  --output "$HOME/.local/run/basaltic/aws.jwt"
```

O comando permanece em execução. Use `--once` para uma tarefa curta e única; esse arquivo não será renovado. O modo contínuo remove o arquivo ao parar e remove uma prova expirada se a renovação falhar. Um segundo helper não pode controlar o mesmo arquivo de saída.

Para um serviço executado com o usuário `app` já existente, use uma unidade systemd separada:

```ini /etc/systemd/system/basaltic-aws-identity.service theme={null}
[Unit]
Description=Basaltic VM identity for AWS
Wants=network-online.target
After=network-online.target

[Service]
User=app
Group=app
RuntimeDirectory=basaltic-aws-identity
RuntimeDirectoryMode=0700
UMask=0077
ExecStart=/usr/bin/basaltic-guest-agent identity-token --audience sts.amazonaws.com --output /run/basaltic-aws-identity/token
Restart=on-failure
RestartSec=5
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
```

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now basaltic-aws-identity.service
```

Configure a aplicação para aguardar o arquivo de token antes da primeira requisição à AWS. O helper renova as provas de identidade; o SDK AWS as troca e renova as credenciais AWS. Consulte a [configuração AWS](https://docs.basaltic.sh/pt/iam/aws-federation.md#configure-the-workload).

## Revogação e limites

Remover a role, alterar suas permissões ou revogar a sessão de role Basaltic subjacente bloqueia novas emissões por essa autorização. JWTs de identidade existentes continuam utilizáveis até expirarem, no máximo em cinco minutos. São provas bearer, não tokens de uso único.

Credenciais já emitidas por um serviço externo seguem as regras de duração e revogação desse serviço. Uma prova de cinco minutos pode produzir uma sessão AWS mais longa. Para interromper acessos AWS existentes, use também os controles de revogação de sessão da AWS.

Todos os processos que alcançam o endpoint de metadados da VM podem solicitar provas pela role anexada. As permissões do arquivo de token limitam seus leitores locais; não isolam processos capazes de acessar os metadados por conta própria. Use VMs separadas para workloads que exijam identidades de nuvem separadas.

Desanexar uma role interrompe novas provas pelos metadados. Sessões Basaltic existentes ainda podem chamar a [API de tokens](https://docs.basaltic.sh/pt/iam/oidc.md#generate-a-token-through-the-api) até serem revogadas ou expirarem; revogue-as também ao remover o acesso.


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