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.
Die Verbindung folgt nun dem hochgeladenen Dokument: Eine gespeicherte Metadaten-URL und das Zertifikat-Pinning werden entfernt.
Die Änderung macht den letzten bestandenen Verbindungstest 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: 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 und revision_id und veröffentlichen Sie ihn anschließend. 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:

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

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

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