# SAML-IdP-Metadaten in eine Verbindung importieren

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

Wendet ein hochgeladenes SAML-2.0-Metadatendokument des Identitätsanbieters auf eine Enterprise-SAML-Verbindung an.

- Die Identitätsanbieter-Seite der Verbindung (Entity-ID, HTTP-Redirect-Single-Sign-On-URL, Single-Logout-URL) wird durch die Werte aus dem Dokument ersetzt.
- Signaturzertifikate im Dokument, die noch nicht abgelaufen und noch nicht registriert sind, werden hinzugefügt (`source` ist `manual`). Bereits auf der Verbindung vorhandene Zertifikate bleiben aktiv; löschen Sie diese mit [Zertifikat löschen](../connection-certificates/delete.md).
- Die Verbindung folgt nun dem hochgeladenen Dokument: Eine gespeicherte Metadaten-URL und das Zertifikat-Pinning werden entfernt.
- Die Änderung macht den letzten bestandenen [Verbindungstest](test.md) ungültig; zum Aktivieren der Verbindung ist ein neuer bestandener Test erforderlich.

Bei einer **aktiven** Verbindung wird ein Dokument, das die Entity-ID oder die SSO-URL des Identitätsanbieters ändert oder ein Signatur-Pinning entfernt, nicht angewendet. Der gesamte Import wird zu einer [Entwurfsrevision](revisions.md): Die Antwort zeigt die unveränderte Live-Identitätsanbieter-Seite, `added_certificate_fingerprints` ist leer und `revision` ist gesetzt. Testen Sie den Entwurf mit [Verbindung testen](test.md) und `revision_id` und [veröffentlichen Sie ihn anschließend](publish-revision.md). Andere Importe (neue Zertifikate, SLO-URL, MFA-Werte) werden direkt angewendet.

Das Dokument wird mit strikten Grenzen geparst (höchstens 1 MiB, kein `DOCTYPE`). Ist das Dokument ungültig, nennt die Antwort den Grund nicht, und weder der Grund noch der Dokumentinhalt werden protokolliert. Ein Dokument mit mehreren `EntityDescriptor`-Elementen benötigt `entity_id`. Die Anfrage akzeptiert keinen `If-Match`-Header, weil SAML-Material keine Version hat. Schreibvorgänge werden als `connection.idp_metadata_imported` auditiert, zusätzlich als `connection.idp_certificate_added` für jedes neue Zertifikat.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der Enterprise-SAML-Verbindung (`conn_…`). |
| `metadata_xml` | string | ja | Das Metadatendokument (`EntityDescriptor` oder `EntitiesDescriptor`), höchstens 1 MiB. |
| `entity_id` | string | bei mehreren Entities | Die Entity-ID des Identitätsanbieters, die aus einem Dokument mit mehreren Entities übernommen wird. Bei nur einer Entity muss sie übereinstimmen. |
| `mfa_authn_context_values` | array \| null | nein | SAML-`AuthnContextClassRef`-Werte, die vom Identitätsanbieter als Multi-Faktor-Authentifizierung gelten (höchstens 10). Werden sie angegeben (auch als leere Liste), werden sie gespeichert; wird das Feld weggelassen oder ist `null`, bleiben die gespeicherten Werte erhalten. |

## Antwort

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

| Feld | Beschreibung |
|---|---|
| `idp_entity_id`, `idp_sso_url`, `idp_slo_url` | Die Identitätsanbieter-Seite nach dem Import; `idp_slo_url` ist `null`, wenn das Dokument keinen Single-Logout-Dienst enthält. |
| `certificates` | Die aktiven Signaturzertifikate der Verbindung (siehe [Zertifikate auflisten](../connection-certificates/list.md)). |
| `added_certificate_fingerprints` | SHA-256-Fingerprints der Zertifikate, die dieser Import hinzugefügt hat; bereits registrierte Zertifikate werden nicht aufgeführt. |
| `revision` | Nur wenn der Import zu einer Entwurfsrevision wurde: der Entwurf (siehe [Revisionen auflisten](revisions.md)). |

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Enterprise-Verbindung. |
| 409 | `conflict` | Die Verbindung ist keine SAML-Verbindung, hat noch keine SAML-Konfiguration oder der Import würde mehr als 3 aktive Zertifikate ergeben (es wird nichts geändert). |
| 422 | `validation_failed` | Das Dokument oder ein Feld ist ungültig; `errors[]` verweist auf das Feld (`/metadata_xml`, `/entity_id`, `/mfa_authn_context_values`). In Staging- und Produktionsumgebungen wird ein Test-Identitätsanbieter ebenfalls unter `/metadata_xml` abgelehnt: eine Entity-ID unter der reservierten Domain `.invalid` oder der öffentliche Testschlüssel des [lokalen Mock-Servers](/docs/cli/mock-server). |
| 413 | `payload_too_large` | Der Anfragetext ist größer als 4 MiB. |
| 400 | `unknown_field` | Der Anfragetext enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |

## Beispiel

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