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

# Federación con AWS

> Usa la identidad de VM Basaltic en AWS y la identidad de cargas AWS en Basaltic, con credenciales temporales en ambos sentidos.

Ambos sentidos usan un JWT de identidad separado seguido de un intercambio de credenciales. Ninguno exige copiar una clave de acceso de larga duración a la carga de destino.

| Dirección | Emisión del JWT de identidad | Intercambio |
| - | - | - |
| Basaltic → AWS | Endpoint de metadatos de la VM Basaltic o API de tokens | `AssumeRoleWithWebIdentity` de AWS STS |
| AWS → Basaltic | `GetWebIdentityToken` de AWS STS | `AssumeRoleWithWebIdentity` de Basaltic |

## Basaltic a AWS

También puedes usar una sesión Basaltic autenticada de rol o cuenta de servicio. Llama a la [API de tokens](https://docs.basaltic.sh/es/iam/oidc.md#generate-a-token-through-the-api) con `audience: "sts.amazonaws.com"` e intercambia su JWT en AWS STS. En la política de confianza AWS siguiente, usa el sujeto exacto del rol o cuenta de servicio de esa prueba. El flujo de VM siguiente usa el endpoint de metadatos y el helper guest.

Necesitas un administrador en la cuenta AWS de destino, una VM Basaltic con un rol adjunto y el agente guest `1.15.11-1` o posterior para renovar el archivo automáticamente. La VM debe alcanzar AWS STS por HTTPS. AWS debe alcanzar los endpoints públicos de descubrimiento y JWKS de Basaltic.

### Permitir que la VM solicite una prueba para AWS

Concede al rol Basaltic adjunto `iam:GetWebIdentityToken` sobre su propio CRN, restringido a `basalt:IdentityTokenAudience = sts.amazonaws.com`. Usa el [ejemplo de política de identidad de VM](https://docs.basaltic.sh/es/iam/vm-identity.md) y obtén un token dentro de la VM. Su sujeto tiene este formato inmutable:

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

Usa los UUIDs reales de organización, cuenta e instancia en la política de confianza AWS. No los sustituyas por el nombre de la VM ni por un nombre de rol compartido.

### Registrar Basaltic en AWS

En la cuenta AWS de destino, registra el emisor `https://iam.basaltic.sh` con el client ID (audiencia) `sts.amazonaws.com`. Un administrador puede ejecutar:

> [tab] CLI
>
> ```bash theme={null}
> aws iam create-open-id-connect-provider \
>   --url https://iam.basaltic.sh \
>   --client-id-list sts.amazonaws.com
> ```

Si el emisor ya está registrado, reutiliza el ARN del proveedor y confirma que su lista de client IDs incluye `sts.amazonaws.com`. Usa la URL del emisor, no una URL JWKS. AWS obtiene las claves de verificación del documento de descubrimiento de Basaltic. Consulta la [configuración del proveedor OIDC en AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).

Crea un rol AWS con esta política de confianza, sustituyendo `123456789012` por el ID de la cuenta AWS de destino y el sujeto por el sujeto exacto de la 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
> ```

Adjunta una política de permisos AWS para los recursos concretos que necesita la aplicación. La política de confianza permite el intercambio; no concede permisos de S3 ni de otros servicios. Mantén la restricción de sujeto aunque varias cuentas o roles Basaltic compartan el proveedor.

### Configurar la carga

Inicia el [helper de archivo de token](https://docs.basaltic.sh/es/iam/vm-identity.md#maintain-a-token-file) como el usuario de la aplicación. Con el ejemplo systemd de esa página, configura el entorno de la aplicación:

```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` impide que un cliente AWS recurra al endpoint de credenciales de metadatos Basaltic, cuyas credenciales son para Basaltic. No configures claves de acceso AWS estáticas ni otro perfil de credenciales en esta aplicación: pueden tener precedencia sobre el proveedor de identidad web.

La CLI AWS y los SDKs compatibles intercambian el JWT actual del archivo y renuevan las credenciales AWS cuando es necesario. El helper guest renueva el archivo de forma independiente. Comprueba el soporte en el [proveedor de credenciales assume-role](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html) de tu SDK.

```bash theme={null}
aws sts get-caller-identity
```

El ARN devuelto debe ser una sesión de rol asumido de `BasalticWorker` en tu cuenta AWS. Este comando demuestra qué identidad está en uso; prueba también una operación permitida de la aplicación.

Para inspeccionar el intercambio directamente sin una 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
```

Trata `aws-session.json` como una credencial y elimínalo después de usarlo. La clave de acceso, la clave secreta y el token de sesión devueltos son credenciales AWS. Basaltic no los conserva ni renueva en nombre de la aplicación.

Las sesiones AWS duran una hora por defecto y pueden durar desde 900 segundos hasta el máximo del rol. Pueden superar los cinco minutos de la prueba Basaltic. Quitar el rol Basaltic de una VM impide nuevas pruebas; usa los controles de revocación AWS para detener sesiones AWS ya emitidas. Consulta el [comportamiento de sesiones AWS STS](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).

## AWS a Basaltic

La federación saliente de AWS convierte una identidad AWS existente en un JWT firmado separado. Una carga EC2 usa las credenciales de su perfil de instancia para autenticar esa solicitud. Otras credenciales AWS, como un rol asumido o una sesión de IAM Identity Center, también pueden autenticarla cuando esté permitido.

### Habilitar la federación saliente de AWS

Un administrador AWS lo habilita una vez para la cuenta de origen:

> [tab] CLI
>
> ```bash theme={null}
> aws iam enable-outbound-web-identity-federation
> aws iam get-outbound-web-identity-federation-info
> ```

Registra el emisor específico de la cuenta devuelto en `IssuerIdentifier`. Tiene un formato como `https://ACCOUNT-SPECIFIC-ID.tokens.sts.global.api.aws`. No lo sustituyas por el endpoint habitual de la API STS. Consulta la [configuración de federación saliente de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_getting_started.html).

Concede al rol AWS de origen permiso para emitir pruebas para tu audiencia Basaltic. Esta política AWS permite solo la audiencia elegida y un máximo de 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 el emisor AWS en Basaltic

Registra ese emisor exacto en la cuenta Basaltic que contiene el rol de destino.

> [tab] Console
>
> Abre **IAM** → **OIDC providers** → **Create provider**. Introduce `aws`, el emisor específico de la cuenta y `urn:example:basaltic:production` como audiencia 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
> ```

Crea un rol Basaltic llamado `aws-worker`, adjunta sus políticas de permisos Basaltic necesarias y usa esta política de confianza con el ARN real del rol IAM AWS de origen:

```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"]
    }
  ]
}
```

Usa el ARN del rol IAM en el `sub` del JWT verificado, incluida su ruta. Difiere del ARN STS `arn:aws:sts::...:assumed-role/.../session` devuelto por `GetCallerIdentity`. Consulta los [claims de token AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_outbound_token_claims.html).

> [!WARNING]
>
> Esta confianza identifica el rol IAM AWS. Las instancias EC2 que comparten ese rol comparten su sujeto. El verificador OIDC genérico de Basaltic no convierte los claims EC2 personalizados de AWS en condiciones de confianza. Usa un rol AWS dedicado cuando las cargas necesiten accesos Basaltic separados; esta política no selecciona una sola instancia EC2.

### Emitir e intercambiar desde AWS

Usa un endpoint regional de STS y una versión de la CLI AWS que incluya `get-web-identity-token`. Ejecuta con el rol AWS de origen:

```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
```

Basaltic acepta tokens de identidad AWS `RS256` y `ES384`. Las pruebas AWS duran de 60 a 3600 segundos, con un valor predeterminado de 300. El endpoint regional es obligatorio; el endpoint global de STS no atiende esta operación de emisión. Consulta [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html).

Usa el token bearer Basaltic devuelto para las APIs o sus credenciales temporales de clave de acceso para S3 Basaltic. Emite e intercambia de nuevo antes de que caduque la sesión Basaltic. Mantén la respuesta privada y elimínala cuando ya no necesites la sesión.

Eliminar el proveedor Basaltic o cambiar sus audiencias bloquea nuevos intercambios. Revoca las sesiones Basaltic existentes por separado. Deshabilitar la federación saliente de AWS es un cambio para toda la cuenta; hazlo solo cuando ninguna otra integración la necesite. Los JWTs salientes emitidos por AWS no se pueden intercambiar de vuelta en AWS mediante `AssumeRoleWithWebIdentity`.

## Diagnosticar el lado correcto

| Síntoma | Comprueba |
| - | - |
| Los metadatos Basaltic devuelven `401` | Obtén un nuevo token IMDSv2 en la misma VM |
| Los metadatos Basaltic devuelven `403` | Rol adjunto, `iam:GetWebIdentityToken`, condición de audiencia y límite de permisos |
| AWS informa `InvalidIdentityToken` | Usa el JWT de identidad de VM y comprueba descubrimiento del emisor, JWKS, audiencia y caducidad |
| Se deniega el intercambio AWS | ARN del proveedor y condiciones exactas de `aud`/`sub` en la confianza del rol AWS |
| La CLI AWS informa `FeatureDisabled` | Habilita la federación saliente en la cuenta AWS de origen |
| Se deniega AWS `GetWebIdentityToken` | Permiso del rol AWS de origen y sus condiciones de audiencia y duración |
| El intercambio Basaltic devuelve `401` | Emisor AWS específico de la cuenta, audiencia del proveedor y validez del JWT |
| El intercambio Basaltic devuelve `403` | ARN del rol IAM en `sub` y `for_any_value` en la condición de audiencia |
| Una aplicación usa una identidad AWS inesperada | Elimina credenciales o perfiles estáticos con precedencia y confirma su configuración de archivo de identidad web |


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