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.
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 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: 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 y revision_id, y después publíquelo. 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:

{
  "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).
`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).

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

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

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