# Importar metadatos SAML del IdP en una conexión

`POST /v1/connections/{connection_id}:import-metadata` · permiso `connections:write`

Aplica un documento de metadatos SAML 2.0 subido por el proveedor de identidad a una conexión SAML empresarial.

- La parte del proveedor de identidad de la conexión (ID de entidad, URL de inicio de sesión único mediante HTTP-Redirect y URL de cierre de sesión único) se reemplaza por los valores del documento.
- Los certificados de firma del documento que aún no han caducado y que aún no están registrados se añaden (`source` es `manual`). Los certificados que ya están en la conexión siguen activos; para eliminarlos, use [Eliminar un certificado](../connection-certificates/delete.md).
- La conexión ahora sigue el documento subido: se borran una URL de metadatos almacenada y el anclaje de certificados.
- El cambio invalida la última [prueba de conexión](test.md) superada; para activar la conexión se necesita una nueva prueba superada.

En una conexión **activa**, un documento que cambie el ID de entidad o la URL de SSO del proveedor de identidad, o que elimine un anclaje de firma, no se aplica. Toda la importación se convierte en una [revisión en borrador](revisions.md): la respuesta muestra la parte del proveedor de identidad activa, sin cambios, `added_certificate_fingerprints` está vacío y se establece `revision`. Pruebe el borrador con [Probar una conexión](test.md) y `revision_id`, y después [publíquelo](publish-revision.md). Las demás importaciones (nuevos certificados, URL de SLO, valores de MFA) se aplican directamente.

El documento se analiza con límites estrictos (como máximo 1 MiB, sin `DOCTYPE`). Cuando el documento no es válido, la respuesta no indica el motivo y ni el motivo ni el contenido del documento se registran. Un documento con varios elementos `EntityDescriptor` requiere `entity_id`. La solicitud no admite la cabecera `If-Match`, porque el material SAML no tiene versión. Las escrituras se auditan como `connection.idp_metadata_imported`, además de `connection.idp_certificate_added` por cada certificado nuevo.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | ruta | sí | ID de la conexión SAML empresarial (`conn_…`). |
| `metadata_xml` | cadena | sí | El documento de metadatos (`EntityDescriptor` o `EntitiesDescriptor`), de como máximo 1 MiB. |
| `entity_id` | cadena | para varias entidades | El ID de entidad del proveedor de identidad que se tomará de un documento con varias entidades. Con una sola entidad debe coincidir. |
| `mfa_authn_context_values` | array \| null | no | Valores `AuthnContextClassRef` de SAML que el proveedor de identidad considera autenticación multifactor (como máximo 10). Cuando se indican (incluso una lista vacía) se almacenan; cuando se omiten o son `null` se conservan los valores almacenados. |

## Respuesta

`200 OK`:

```json
{
  "idp_entity_id": "https://idp.example.com/entity",
  "idp_sso_url": "https://idp.example.com/sso/redirect",
  "idp_slo_url": null,
  "certificates": [
    {"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
  ],
  "added_certificate_fingerprints": ["3b0c…"]
}
```

| Campo | Descripción |
|---|---|
| `idp_entity_id`, `idp_sso_url`, `idp_slo_url` | La parte del proveedor de identidad después de la importación; `idp_slo_url` es `null` cuando el documento no tiene servicio de cierre de sesión único. |
| `certificates` | Los certificados de firma activos de la conexión (consulte [Listar certificados](../connection-certificates/list.md)). |
| `added_certificate_fingerprints` | Huellas SHA-256 de los certificados que añadió esta importación; los certificados ya registrados no aparecen. |
| `revision` | Solo cuando la importación se convirtió en una revisión en borrador: el borrador (consulte [Listar las revisiones](revisions.md)). |

## Errores

| HTTP | code | Cuándo |
|---|---|---|
| 404 | `not_found` | La conexión no existe en este entorno o no es una conexión empresarial. |
| 409 | `conflict` | La conexión no es una conexión SAML, todavía no tiene configuración SAML o la importación superaría 3 certificados activos (no se cambia nada). |
| 422 | `validation_failed` | El documento o un campo no es válido; `errors[]` apunta al campo (`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). En los entornos de staging y producción también se rechaza un proveedor de identidad de prueba en `/metadata_xml`: un ID de entidad bajo el dominio reservado `.invalid`, o la clave pública de prueba del [servidor simulado local](/docs/cli/mock-server). |
| 413 | `payload_too_large` | El cuerpo de la solicitud supera los 4 MiB. |
| 400 | `unknown_field` | El cuerpo contiene un campo desconocido. |
| 401 | `unauthenticated` | La credencial falta, no es válida o fue revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso necesario. |
| 429 | `rate_limited` | Se superó el límite de frecuencia; reintente después del periodo indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del periodo indicado en `Retry-After`. |

## Ejemplo

```bash
jq -Rs '{metadata_xml: .}' idp-metadata.xml > import.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:import-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @import.json
```

```bash
keenauth connections import-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --metadata-file idp-metadata.xml
```