# 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](../connection-certificates/delete.md).
- 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](test.md) 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](revisions.md) : 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](test.md) et `revision_id`, puis [publiez-le](publish-revision.md). 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` :

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

| 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](../connection-certificates/list.md)). |
| `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](revisions.md)). |

## 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](/docs/cli/mock-server). |
| 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

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