Importer les métadonnées SAML de l'IdP dans une connexion

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

Applique un document de métadonnées SAML 2.0 envoyé par le fournisseur d'identité à une connexion SAML d'entreprise.

La partie fournisseur d'identité de la connexion (ID d'entité, URL de authentification unique en HTTP-Redirect, URL de déconnexion unique) est remplacée par les valeurs du document.
Les certificats de signature présents dans le document qui ne sont pas encore expirés et pas encore enregistrés sont ajoutés (source vaut manual). Les certificats déjà présents sur la connexion restent actifs ; supprimez-les avec Supprimer un certificat.
La connexion suit désormais le document importé : une URL de métadonnées enregistrée et l'épinglage de certificat sont effacés.
Cette modification invalide le dernier test de connexion réussi ; l'activation de la connexion nécessite un nouveau test réussi.

Sur une connexion active, un document qui modifie l'ID d'entité ou l'URL SSO du fournisseur d'identité, ou qui supprime un épinglage de signature, n'est pas appliqué. L'import complet devient une révision en brouillon : la réponse affiche la partie fournisseur d'identité inchangée en production, added_certificate_fingerprints est vide et revision est renseigné. Testez le brouillon avec Tester une connexion et revision_id, puis publiez-le. Les autres imports (nouveaux certificats, URL SLO, valeurs MFA) sont appliqués directement.

Le document est analysé avec des limites strictes (1 MiB au maximum, pas de DOCTYPE). Lorsque le document est invalide, la réponse n'indique pas la raison et ni la raison ni le contenu du document ne sont journalisés. Un document contenant plusieurs éléments EntityDescriptor exige entity_id. La requête n'accepte pas d'en-tête If-Match, car le matériel SAML n'a pas de version. Les écritures sont auditées sous connection.idp_metadata_imported, ainsi que connection.idp_certificate_added pour chaque nouveau certificat.

Requête

Champ	Type	Requis	Description
`connection_id`	chemin	oui	ID de la connexion SAML d'entreprise (`conn_…`).
`metadata_xml`	chaîne	oui	Le document de métadonnées (`EntityDescriptor` ou `EntitiesDescriptor`), 1 MiB au maximum.
`entity_id`	chaîne	pour plusieurs entités	L'ID d'entité du fournisseur d'identité à prendre dans un document contenant plusieurs entités. Avec une seule entité, il doit correspondre.
`mfa_authn_context_values`	tableau \| null	non	Valeurs `AuthnContextClassRef` SAML qui comptent comme authentification multifacteur par le fournisseur d'identité (10 au maximum). Lorsqu'elles sont fournies (même une liste vide), elles sont enregistrées ; si elles sont omises ou `null`, les valeurs enregistrées sont conservées.

Réponse

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

Champ	Description
`idp_entity_id`, `idp_sso_url`, `idp_slo_url`	La partie fournisseur d'identité après l'import ; `idp_slo_url` vaut `null` lorsque le document ne contient pas de service de déconnexion unique.
`certificates`	Les certificats de signature actifs de la connexion (voir Lister les certificats).
`added_certificate_fingerprints`	Empreintes SHA-256 des certificats ajoutés par cet import ; les certificats déjà enregistrés ne sont pas listés.
`revision`	Uniquement lorsque l'import est devenu une révision en brouillon : le brouillon (voir Lister les révisions).

Erreurs

HTTP	code	Quand
404	`not_found`	La connexion n'existe pas dans cet environnement ou n'est pas une connexion d'entreprise.
409	`conflict`	La connexion n'est pas une connexion SAML, n'a pas encore de configuration SAML, ou l'import dépasserait 3 certificats actifs (rien n'est modifié).
422	`validation_failed`	Le document ou un champ est invalide ; `errors[]` indique le champ (`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). Dans les environnements de staging et de production, un fournisseur d'identité de test est aussi refusé à `/metadata_xml` : un ID d'entité sous le domaine réservé `.invalid`, ou la clé publique de test du serveur mock local.
413	`payload_too_large`	Le corps de la requête dépasse 4 MiB.
400	`unknown_field`	Le corps contient un champ inconnu.
401	`unauthenticated`	L'identifiant est absent, invalide ou révoqué.
403	`insufficient_permissions`	L'identifiant ne dispose pas de l'autorisation requise.
429	`rate_limited`	La limite de débit a été dépassée ; réessayez après la durée indiquée par `Retry-After`.
503	`service_unavailable`	Une dépendance est temporairement indisponible ; réessayez après la durée indiquée par `Retry-After`.

Exemple

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