> ## 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 identidad de VM

> Obtén pruebas OIDC vinculadas a una audiencia desde una instancia Basaltic y renuévalas para servicios externos.

Una VM Basaltic puede obtener un JWT de identidad desde su servicio de metadatos sin almacenar credenciales de larga duración. Úsalo con [AWS STS](https://docs.basaltic.sh/es/iam/aws-federation.md) u otro servicio que confíe en el emisor OIDC de Basaltic.

La VM necesita un [rol IAM adjunto](https://docs.basaltic.sh/es/compute/instances.md#change-an-existing-instances-role). Sus políticas deben permitir `iam:GetWebIdentityToken` sobre el CRN de ese rol. Restringe la audiencia al servicio 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"]
    }]
  }]
}
```

Aplícalo como [política inline o adjunta al rol](https://docs.basaltic.sh/es/iam/policies.md). También se aplican los límites de permisos del rol. `basalt:IdentityTokenDurationSeconds` contiene la duración solicitada en segundos, incluido el valor predeterminado `300` cuando no se indica una duración.

## Solicitar un token dentro de la VM

Primero obtén un token de sesión IMDSv2. Después solicita un JWT de identidad con una audiencia 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
```

La respuesta JSON contiene `token` y `expires_at`. La duración predeterminada es 300 segundos; puedes solicitar entre 60 y 300 segundos. Las solicitudes repetidas pueden devolver un token en caché aún válido, así que usa la caducidad devuelta. Cada solicitud comprueba los permisos actuales del rol, incluso al usar la caché.

Este endpoint siempre exige IMDSv2, aunque los metadatos normales permitan IMDSv1. Solo acepta `audience` y el campo opcional `duration_seconds`. La plataforma aporta la identidad de la VM; una solicitud no puede elegir otra VM, cuenta, organización o sujeto. La audiencia `basaltic` está reservada para el acceso a la API y se rechaza aquí.

Los tres tokens involucrados son distintos:

| Token | Finalidad |
| - | - |
| Token de sesión IMDSv2 | Acceso al servicio de metadatos de esta VM |
| JWT de identidad de VM | Prueba presentada a un intercambio externo de credenciales |
| Token de acceso a la API Basaltic | Llamadas a las APIs Basaltic mediante el rol adjunto |

## Claims de identidad

El emisor es `https://iam.basaltic.sh`. Los JWTs usan ES256 e incluyen `iss`, `sub`, `aud`, `iat`, `exp` y `jti`.

El sujeto es:

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

Usa el sujeto exacto en la política de confianza del destino. Estos UUIDs son inmutables. Renombrar un recurso no cambia su identidad; recrear una VM con el mismo nombre genera otro sujeto. Dos VMs que comparten un rol Basaltic siguen teniendo sujetos distintos.

El destino debe verificar la firma con el [JWKS](https://docs.basaltic.sh/es/iam/oidc.md#discovery-and-keys) descubierto del emisor antes de confiar en los claims. Decodificar un JWT sin verificarlo sirve para inspeccionar su contenido, pero no demuestra nada.

## Mantener un archivo de token

La versión `1.15.11-1` o posterior del agente guest incluye el comando `identity-token`. Actualiza `basaltic-guest-agent` desde el repositorio de paquetes Basaltic configurado en la VM antes de usarlo.

Ejecuta el helper con el mismo usuario de la aplicación y un directorio de salida privado. Renueva la prueba antes de caducar y sustituye atómicamente un archivo con 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"
```

El comando permanece en ejecución. Usa `--once` para una única tarea breve; ese archivo no se renueva. El modo continuo elimina el archivo al detenerse y elimina una prueba caducada si falla la renovación. Un segundo helper no puede controlar el mismo archivo de salida.

Para un servicio ejecutado con el usuario `app` ya existente, usa una unidad 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
```

Configura la aplicación para esperar al archivo de token antes de su primera solicitud a AWS. El helper renueva las pruebas de identidad; el SDK AWS las intercambia y renueva las credenciales AWS. Consulta la [configuración AWS](https://docs.basaltic.sh/es/iam/aws-federation.md#configure-the-workload).

## Revocación y límites

Eliminar el rol, cambiar sus permisos o revocar la sesión de rol Basaltic subyacente bloquea nuevas emisiones mediante esa autorización. Los JWTs de identidad existentes siguen siendo utilizables hasta caducar, como máximo en cinco minutos. Son pruebas bearer, no tokens de un solo uso.

Las credenciales ya emitidas por un servicio externo siguen las reglas de duración y revocación de ese servicio. Una prueba de cinco minutos puede producir una sesión AWS más larga. Para detener el acceso AWS existente, usa también los controles de revocación de sesiones de AWS.

Todos los procesos que alcanzan el endpoint de metadatos de la VM pueden solicitar pruebas mediante el rol adjunto. Los permisos del archivo de token limitan a sus lectores locales; no aíslan procesos que pueden acceder a los metadatos por sí mismos. Usa VMs separadas para cargas que necesiten identidades de nube separadas.

Desvincular un rol detiene nuevas pruebas por metadatos. Las sesiones Basaltic existentes aún pueden llamar a la [API de tokens](https://docs.basaltic.sh/es/iam/oidc.md#generate-a-token-through-the-api) hasta ser revocadas o caducar; revócalas también al retirar el acceso.


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