# Establecer el inicio de sesión iniciado por el IdP para una conexión SAML

`PUT /v1/connections/{connection_id}/idp-initiated` · permiso `connections:write`

Permite o desactiva el inicio de sesión iniciado por el IdP (una respuesta SAML no solicitada que se envía desde el portal de aplicaciones del proveedor de identidad) para una conexión SAML empresarial, y establece las aplicaciones a las que el usuario puede acceder. Está desactivado de forma predeterminada.

- **Reemplazo completo:** cada solicitud escribe los tres campos. Un `idp_initiated_default_application_id` omitido y un `idp_initiated_allowed_application_ids` vacío se borran.
- **Destinos:** cada aplicación debe existir en este entorno, iniciar sesión de los usuarios mediante un navegador (no de máquina a máquina, de gestión ni de cliente con documento de metadatos de ID de cliente) y tener un `initiate_login_uri`. Después de iniciar sesión, el navegador se envía a esa dirección con `iss`, y la aplicación inicia su propia solicitud de autorización con `state` y PKCE.
- **RelayState:** cuando el proveedor de identidad envía un RelayState, solo selecciona una aplicación si coincide byte a byte con el `client_id` de esa aplicación y la aplicación es la predeterminada o está en la lista de permitidas. RelayState nunca se trata como una URL.
- **Seguridad:** esta configuración acepta respuestas que sus usuarios no iniciaron, por lo que un usuario del panel necesita una autenticación de nivel superior reciente y el rol `owner` o `admin`. El Portal de administración no puede cambiarla.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | ruta | sí | ID de la conexión SAML empresarial (`conn_…`). |
| `If-Match` | encabezado | no | El `ETag` de la conexión. Un valor desactualizado falla con `412`. |
| `allow_idp_initiated` | booleano | sí | Acepta respuestas SAML no solicitadas. `true` requiere `idp_initiated_default_application_id`. |
| `idp_initiated_default_application_id` | string \| null | cuando está habilitado | Aplicación (`app_…`) que se usa cuando el RelayState está vacío. |
| `idp_initiated_allowed_application_ids` | array | no | Aplicaciones (`app_…`) que un RelayState puede seleccionar; únicas, como máximo 20. |

## Respuesta

`200 OK` con la conexión (véase [Obtener una conexión](../connections/get.md)) y su nuevo `ETag`. La conexión muestra los valores almacenados en `allow_idp_initiated`, `idp_initiated_default_application_id` y `idp_initiated_allowed_application_ids`.

## Errores

| HTTP | código | Cuándo |
|---|---|---|
| 404 | `not_found` | La conexión no existe en este entorno. |
| 412 | `precondition_failed` | `If-Match` no coincide con la versión actual. |
| 422 | `validation_failed` | La conexión no es una conexión SAML empresarial, falta la aplicación predeterminada cuando está habilitado, o una aplicación no cumple las reglas de destino; `errors[]` indica el campo. |
| 400 | `unknown_field` | El cuerpo contiene un campo desconocido. |
| 401 | `unauthenticated` | La credencial falta, no es válida o ha sido revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso requerido. |
| 403 | `step_up_required` | Un usuario del panel no ha completado una autenticación de nivel superior reciente. |
| 429 | `rate_limited` | Se superó el límite de solicitudes; reintente después del período indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del período indicado en `Retry-After`. |

## Ejemplo

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'
```

```bash
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'
```