# IdP-initiierte Anmeldung für eine SAML-Verbindung festlegen

`PUT /v1/connections/{connection_id}/idp-initiated` · Berechtigung `connections:write`

Erlaubt oder deaktiviert die IdP-initiierte Anmeldung (eine unaufgeforderte SAML-Antwort, die vom App-Portal des Identitätsanbieters gesendet wird) für eine SAML-Verbindung für Unternehmen und legt fest, in welche Anwendungen Benutzer gelangen dürfen. Standardmäßig ist sie deaktiviert.

- **Vollständiger Ersatz:** Jede Anfrage schreibt alle drei Felder. Ein weggelassenes `idp_initiated_default_application_id` und ein leeres `idp_initiated_allowed_application_ids` werden gelöscht.
- **Ziele:** Jede Anwendung muss in dieser Umgebung existieren, Benutzer über einen Browser anmelden (nicht Machine-to-Machine, Management oder Client mit Client-ID-Metadatendokument) und ein `initiate_login_uri` besitzen. Nach der Anmeldung wird der Browser mit `iss` an diese Adresse weitergeleitet, und die Anwendung startet ihre eigene Autorisierungsanfrage mit `state` und PKCE.
- **RelayState:** Sendet der Identitätsanbieter einen RelayState, wählt dieser nur dann eine Anwendung aus, wenn er byte-genau der `client_id` dieser Anwendung entspricht und die Anwendung die Standardanwendung oder in der Liste der erlaubten Anwendungen ist. Der RelayState wird niemals als URL behandelt.
- **Sicherheit:** Diese Einstellung akzeptiert Antworten, die Ihre Benutzer nicht angestoßen haben. Daher benötigt ein Dashboard-Benutzer eine aktuelle Step-up-Authentifizierung und die Rolle `owner` oder `admin`. Das Admin-Portal kann diese Einstellung nicht ändern.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der SAML-Verbindung für Unternehmen (`conn_…`). |
| `If-Match` | Header | nein | Das `ETag` der Verbindung. Ein veralteter Wert schlägt mit `412` fehl. |
| `allow_idp_initiated` | boolean | ja | Unaufgeforderte SAML-Antworten akzeptieren. `true` erfordert `idp_initiated_default_application_id`. |
| `idp_initiated_default_application_id` | string \| null | bei Aktivierung | Anwendung (`app_…`), die verwendet wird, wenn der RelayState leer ist. |
| `idp_initiated_allowed_application_ids` | array | nein | Anwendungen (`app_…`), die ein RelayState auswählen darf; eindeutig, höchstens 20. |

## Antwort

`200 OK` mit der Verbindung (siehe [Verbindung abrufen](../connections/get.md)) und ihrem neuen `ETag`. Die Verbindung zeigt die gespeicherten Werte in `allow_idp_initiated`, `idp_initiated_default_application_id` und `idp_initiated_allowed_application_ids` an.

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht. |
| 412 | `precondition_failed` | `If-Match` stimmt nicht mit der aktuellen Version überein. |
| 422 | `validation_failed` | Die Verbindung ist keine SAML-Verbindung für Unternehmen, die Standardanwendung fehlt bei aktivierter Option, oder eine Anwendung erfüllt die Zielregeln nicht; `errors[]` verweist auf das Feld. |
| 400 | `unknown_field` | Der Body enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten besitzen nicht die erforderliche Berechtigung. |
| 403 | `step_up_required` | Ein Dashboard-Benutzer hat keine aktuelle Step-up-Authentifizierung abgeschlossen. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`. |
| 503 | `service_unavailable` | Ein Dienst ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`. |

## Beispiel

```bash
curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'
```

```bash
keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'
```