SAML-SP-Metadaten einer Verbindung herunterladen

GET /v1/connections/{connection_id}/sp-metadata · Berechtigung connections:read

Lädt das signierte SAML-2.0-Metadatendokument des Service Providers (SP) einer Enterprise-SAML-Verbindung herunter: die Datei, die der Administrator des Identitätsanbieters im Identitätsanbieter hochlädt. Es ist dasselbe Dokument, das die öffentliche Metadatenadresse der Verbindung (https://<sp host>/saml/<conn_…>/metadata) ausliefert:

entityID, validUntil (7 Tage in der Zukunft) und cacheDuration (PT24H);
die Signatur- und Verschlüsselungszertifikate (während eines jährlichen Schlüsselrotationsfensters jeweils zwei);
die unterstützten NameID-Formate, der Assertion Consumer Service (HTTP-POST) und die Single-Logout-Endpunkte;
eine umschließende XML-Signatur, erstellt mit dem aktiven SP-Signaturschlüssel der Verbindung.

Die SP-Schlüssel werden bei der ersten Verwendung erstellt, falls sie noch nicht existieren. Das Dokument enthält kein Geheimnis. Lesezugriffe werden nicht protokolliert.

Mit revision_id erhalten Sie stattdessen das Dokument einer Entwurfsrevision. Bei einer SP-Host-Migration enthält es die Endpunkte auf dem neuen Host: Geben Sie es dem Administrator des Identitätsanbieters, bevor Sie die Revision veröffentlichen.

Anfrage

Feld	Typ	Pflicht	Beschreibung
`connection_id`	Pfad	ja	ID der Enterprise-Verbindung (`conn_…`).
`revision_id`	Query	nein	Eine Entwurfsrevision der Verbindung (`connrev_…`).

Antwort

200 OK mit dem XML-Dokument als Body:

Header	Wert
`Content-Type`	`application/samlmetadata+xml`
`Content-Disposition`	`attachment; filename="<conn_…>-sp-metadata.xml"`
`Cache-Control`	`no-store`

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    ID="_…" entityID="https://acme.eu.keenauth.app/saml/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/metadata"
    validUntil="2026-11-02T10:00:00Z" cacheDuration="PT24H">
  <ds:Signature>…</ds:Signature>
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    …
  </md:SPSSODescriptor>
</md:EntityDescriptor>

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 oder hat noch keine SAML-Konfiguration.
422	`validation_failed`	`revision_id` ist fehlerhaft oder doppelt angegeben (`invalid_value`, `repeated`) oder keine Entwurfsrevision dieser Verbindung (`not_found`); `errors[]` verweist auf `/revision_id`.
401	`unauthenticated`	Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403	`insufficient_permissions`	Die Anmeldeinformation besitzt die erforderliche Berechtigung nicht.
429	`rate_limited`	Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`.
503	`service_unavailable`	Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`.

Beispiel

curl -o sp-metadata.xml "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/sp-metadata" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth connections sp-metadata conn_01j9xp6q0r1s5t7v9w1x3y5z7b --file sp-metadata.xml

Ohne --file schreibt die CLI das XML auf die Standardausgabe. Eine vorhandene Datei wird nie überschrieben.