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

> Intercambia identidades de cargas de trabajo por credenciales temporales sin distribuir claves de acceso de larga duración.

Usa OIDC cuando una carga de trabajo ya tiene una identidad y necesita credenciales temporales en otro sistema. El emisor firma un JWT de corta duración. El destino comprueba su firma, emisor, audiencia y sujeto antes de emitir sus propias credenciales.

| Carga de trabajo | Prueba de identidad | Intercambio |
| - | - | - |
| GitHub Actions → Basaltic | JWT OIDC del job de GitHub | [GitHub Actions](https://docs.basaltic.sh/es/iam/github-actions.md) |
| Sesión de API Basaltic → plataforma externa | `GetWebIdentityToken` con la audiencia de destino | [API de tokens](#generate-a-token-through-the-api) |
| Carga externa → Basaltic | JWT de un emisor OIDC registrado en la cuenta | `AssumeRoleWithWebIdentity` de Basaltic |
| Carga AWS → Basaltic | JWT de `GetWebIdentityToken` de AWS STS | [AWS a Basaltic](https://docs.basaltic.sh/es/iam/aws-federation.md#aws-to-basaltic) |
| VM Basaltic → AWS | JWT de identidad de la VM del servicio de metadatos | [Basaltic a AWS](https://docs.basaltic.sh/es/iam/aws-federation.md#basaltic-to-aws) |
| VM Basaltic → otro servicio que confía en OIDC | El mismo endpoint de identidad de VM, con la audiencia de ese servicio | [Tokens de identidad de VM](https://docs.basaltic.sh/es/iam/vm-identity.md) |

Una prueba de identidad y un token de acceso a la API tienen fines distintos. Un JWT OIDC acredita la identidad durante el intercambio. Las credenciales resultantes autorizan solicitudes según los permisos del rol de destino. Los tokens bearer de la API Basaltic usan una clave de firma separada y no sustituyen a los tokens de identidad de VM.

## Generar un token mediante la API

Una cuenta de servicio autenticada o una sesión de rol asumido puede llamar a `GetWebIdentityToken`. Los usuarios humanos primero asumen un rol de la cuenta. La cuenta seleccionada debe coincidir con la carga autenticada. Los metadatos siguen disponibles para que la VM obtenga su prueba directamente.

Concede `iam:GetWebIdentityToken` sobre el CRN del propio rol o cuenta de servicio del solicitante. Restringe `basalt:IdentityTokenAudience` al destino. Por ejemplo:

```json theme={null}
{
  "version": "2024-01-01",
  "statements": [{
    "effect": "allow",
    "actions": ["iam:GetWebIdentityToken"],
    "resources": ["crn:iam::production:service-account/deploy-bot"],
    "conditions": [{
      "operator": "equals",
      "key": "basalt:IdentityTokenAudience",
      "values": ["https://deploy.example.com"]
    }]
  }]
}
```

Usa un token bearer válido de la API Basaltic en `BASALTIC_TOKEN`. Mantén privada la respuesta:

```bash theme={null}
umask 077
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BASALTIC_TOKEN" \
  -H 'X-Account-Id: production' \
  -H 'Content-Type: application/json' \
  -d '{"audience":"https://deploy.example.com","duration_seconds":300}' \
  https://iam.basaltic.sh/v1/get-web-identity-token > identity-response.json
jq -r .token identity-response.json > identity.jwt
rm -f identity-response.json
```

La respuesta contiene `token` y `expires_at`. La duración predeterminada es de 300 segundos; los valores explícitos van de 60 a 300. La sesión de origen debe seguir siendo válida durante ese período. `basalt:IdentityTokenDurationSeconds` puede restringirlo más. Renueva llamando de nuevo al endpoint.

El sujeto se deriva de la identidad autenticada. No se aceptan nombres, sujetos elegidos por el solicitante ni claims JWT arbitrarios:

```text theme={null}
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:role:ROLE_UUID
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:service-account:SERVICE_ACCOUNT_UUID
org:ORGANIZATION_UUID:account:ACCOUNT_UUID:instance:INSTANCE_UUID
```

Una sesión directa de metadatos conserva el sujeto de la VM. Una sesión encadenada representa su rol de destino. Revocar la sesión de origen o retirar su permiso bloquea nuevas emisiones por la API. Desvincular el rol de una VM bloquea la emisión por metadatos; revoca también las sesiones Basaltic existentes para detener la emisión por la API. Las pruebas ya emitidas siguen siendo válidas hasta caducar.

## Elegir la audiencia de destino

La `audience` se elige para la plataforma receptora, no está fijada a AWS. Usa el valor que espera esa plataforma y configura permisos de emisión y confianza correspondientes. Los ejemplos de AWS usan `sts.amazonaws.com`; otro servicio puede exigir una URL, un identificador de cliente o una URN. La audiencia `basaltic` está reservada para tokens de la API Basaltic.

El claim JWT es `aud`. La forma `iam.basaltic.sh:aud` es una clave de condición de confianza de AWS que hace referencia a ese claim. Otras plataformas usan su propia configuración de mapeo de claims. Deben admitir JWTs externos de cargas de trabajo y firmas ES256 de Basaltic; una integración de inicio de sesión OIDC interactivo por sí sola no basta.

## Aceptar una identidad externa

Deben superarse tres comprobaciones independientes:

1. Registra el emisor en la **misma cuenta que el rol de destino**, con las audiencias que acepta esa cuenta.
2. Añade el CRN del proveedor a la política de confianza del rol y restringe el sujeto.
3. Adjunta al rol políticas de permisos para las operaciones que necesita la carga.

El registro no concede permisos. La confianza permite asumir el rol; las políticas de permisos determinan qué puede hacer la sesión resultante.

Consulta [cómo registrar un proveedor](https://docs.basaltic.sh/es/iam/roles.md#trusting-an-oidc-provider) desde Console y la API. La URL del emisor debe usar HTTPS. Su documento de descubrimiento y JWKS deben ser accesibles por internet. El descubrimiento debe indicar el mismo emisor y los algoritmos de firma compatibles. El emisor y el nombre del proveedor son inmutables; las audiencias, la descripción y las etiquetas se pueden actualizar.

Basaltic valida la firma y la caducidad del JWT y exige que al menos una audiencia coincida con la lista actual del proveedor. Un emisor registrado en otra cuenta no establece confianza en tu cuenta.

## Restringir la confianza

Vincula siempre la confianza al sujeto previsto. Usa también una condición de audiencia cuando un proveedor acepte varias audiencias, pero el rol deba aceptar solo una.

```json theme={null}
{
  "principals": ["crn:iam::production:oidc-provider/workload-issuer"],
  "conditions": [
    {
      "operator": "equals",
      "key": "basalt:webidentity:Subject",
      "values": ["YOUR_EXACT_WORKLOAD_SUBJECT"]
    },
    {
      "operator": "equals",
      "set_operator": "for_any_value",
      "key": "basalt:webidentity:Audience",
      "values": ["urn:example:basaltic:production"]
    }
  ]
}
```

`Subject` es una cadena. `Audience` es un conjunto, aunque el JWT contenga una sola audiencia: su condición necesita `set_operator: "for_any_value"` para comprobar pertenencia. Una condición escalar `equals` en `Audience` no coincide con ese conjunto.

Los proveedores genéricos de clientes exponen el emisor, el sujeto y la audiencia verificados para evaluar la confianza. Los claims personalizados arbitrarios del JWT no están disponibles como claves de política. No supongas que un claim de instancia EC2, una etiqueta de job de CI u otro campo personalizado restringe la confianza, salvo que el propio sujeto compatible aporte esa restricción.

Para GitHub Actions, usa el sujeto exacto emitido para tu workflow, incluidos los IDs inmutables del propietario y del repositorio cuando existan. Restringe la organización o el repositorio y la rama o el entorno previstos. Los proveedores GitHub exigen una restricción positiva de organización o repositorio en el sujeto. El nombre de sesión es una etiqueta de auditoría; no cambia el sujeto verificado.

## Intercambiar la prueba

Envía el JWT y el CRN completo del rol de destino al endpoint público de IAM. El intercambio usa el propio JWT y no requiere una clave de acceso ni un token bearer Basaltic existente.

```http theme={null}
POST https://iam.basaltic.sh/v1/assume-role-with-web-identity
Content-Type: application/json

{
  "role": "crn:iam::production:role/deploy",
  "web_identity_token": "SIGNED_OIDC_JWT",
  "session_name": "deploy-main",
  "duration_seconds": 900
}
```

El CRN completo del rol selecciona la cuenta. No hay un campo `account` en la solicitud. La respuesta contiene credenciales temporales de clave de acceso y un token bearer. Usa el bearer para las APIs Basaltic y las credenciales temporales para el endpoint compatible con S3. Consulta [autenticación](https://docs.basaltic.sh/es/authentication.md).

Las sesiones de rol Basaltic duran una hora por defecto. Una duración explícita debe ser de al menos 900 segundos y respetar el máximo configurado del rol, hasta 12 horas. La caducidad de la prueba determina hasta cuándo se puede intercambiar; no acorta una sesión ya emitida.

## Renovación y revocación

Obtén una nueva prueba de identidad del emisor e intercámbiala antes de que caduque la sesión Basaltic. Este intercambio no tiene refresh token OIDC.

Actualizar las audiencias de un proveedor o eliminarlo impide nuevos intercambios que dejen de cumplir el registro. Cambiar la confianza del rol afecta a nuevos intercambios. Las sesiones existentes siguen siendo válidas hasta caducar o revocarse. [Revoca una sesión](https://docs.basaltic.sh/es/iam/roles.md) para invalidar su bearer y sus credenciales temporales. Recrear un proveedor con el mismo nombre no restaura su vínculo de confianza anterior; actualiza la política del rol para autorizar al nuevo proveedor.

Los proveedores marcados como `is_system` son gestionados por la plataforma y no se pueden modificar ni eliminar. Las cargas de clientes deben registrar su propio emisor accesible públicamente.

## Descubrimiento y claves

Basaltic publica dos documentos de metadatos con fines distintos:

| URL | Finalidad |
| - | - |
| `https://iam.basaltic.sh/.well-known/openid-configuration` | Federación externa de identidad de cargas de trabajo |
| `https://iam.basaltic.sh/.well-known/workload-jwks.json` | Claves públicas de verificación de JWTs de identidad de cargas de trabajo |
| `https://iam.basaltic.sh/.well-known/oauth-authorization-server` | Metadatos del servidor de autorización OAuth de la API Basaltic |
| `https://iam.basaltic.sh/.well-known/jwks.json` | Claves públicas de tokens de la API Basaltic |

Descubre y almacena en caché el JWKS adecuado; no fijes una sola clave de firma. Durante la rotación se pueden publicar varias claves públicas. Verifica `kid`, algoritmo, emisor, audiencia, sujeto y caducidad del JWT.

## Resolución de problemas

| Resultado | Comprueba |
| - | - |
| El intercambio devuelve `401` | Registro del emisor en la cuenta de destino, firma, caducidad, audiencia permitida y acceso al descubrimiento y JWKS |
| El intercambio devuelve `403` | Confianza del rol, sujeto exacto, operador de conjunto de audiencia y estado de cuenta u organización |
| El intercambio funciona, pero una solicitud a la API devuelve `403` | Permisos del rol, límites y CRN del recurso autorizado |
| Una sesión sigue funcionando tras eliminar el proveedor | Revoca la sesión existente; eliminar el proveedor bloquea nuevos intercambios |
| Una carga recreada no puede asumir el rol anterior | Compara su sujeto inmutable y actualiza explícitamente la confianza si la sustitución debe tener acceso |


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