# 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](revisions.md). Bei einer [SP-Host-Migration](migrate-sp-host.md) 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` |

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

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

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