OIDC-Konfiguration einer Verbindung anlegen oder ersetzen

PUT /v1/connections/{connection_id}/oidc · Berechtigung connections:write

Legt die Konfiguration der vertrauenden Partei einer Unternehmens-OIDC-Verbindung an oder ersetzt sie vollständig.

Das Client-Geheimnis ist nur schreibbar: Es wird nie zurückgegeben, nie protokolliert und nie im Audit-Log festgehalten. Wenn Sie ohne client_secret aktualisieren, bleibt das gespeicherte Geheimnis erhalten. private_key_jwt entfernt es (der Signierschlüssel der Umgebung signiert die Client-Assertion). Ein geänderter issuer löscht das gespeicherte Discovery-Dokument. Ein geänderter issuer oder client_id macht den letzten bestandenen Verbindungstest ungültig. Das Senden derselben Konfiguration schreibt nichts. Schreibvorgänge werden als connection.protocol_config_created oder connection.oidc_config_updated protokolliert (nur geänderte Felder; das Geheimnis erscheint nur als client_secret_set).

Bei einer aktiven Verbindung wird eine Aktualisierung, die issuer oder client_id ändert, nicht sofort angewendet. Die gesamte Anfrage (einschließlich eines neuen Geheimnisses) wird zu einer Entwurfsrevision: Die Antwort ist 200 OK mit der unveränderten live Konfiguration, dem unveränderten ETag und einem Feld revision. Testen Sie den Entwurf mit Eine Verbindung testen und revision_id und veröffentlichen Sie ihn anschließend. Andere Aktualisierungen werden direkt angewendet.

Anfrage

Feld Typ Erforderlich Beschreibung
connection_id path ja ID der Unternehmens-OIDC-Verbindung (conn_…).
If-Match header bei Aktualisierung Das ETag aus dem letzten Lese- oder Schreibvorgang. Fehlt es bei einer Aktualisierung: 428; veraltet: 412. Bei der erstmaligen Anlage nicht senden.
sp_host string bei erstmaliger Anlage Aktiver Host dieser Umgebung (Kleinbuchstaben). Bei Aktualisierung leer oder der gespeicherte Host.
issuer string ja Absolute https-URL ohne Query oder Fragment, höchstens 512 Byte.
client_id string ja 1–255 Byte, keine Steuerzeichen.
client_auth_method string ja private_key_jwt (empfohlen; kein Geheimnis wird gespeichert), client_secret_basic oder client_secret_post.
client_secret string nein Nur schreibbar, höchstens 1024 Byte. Wird bei Aktualisierung ohne Angabe beibehalten. Bei private_key_jwt nicht zulässig.
client_secret_expires_at string | null nein Zeitpunkt, zu dem der Identitätsanbieter das Geheimnis ablaufen lässt (RFC 3339). Nur zusammen mit client_secret.
provider_profile string nein entra, okta, google, keycloak, ping, onelogin, jumpcloud oder generic (Standard).
entra_tenant_id string bei entra Die Mandanten-ID von Microsoft Entra (UUID); nur für das Profil entra.

Antwort

201 Created beim erstmaligen Schreibvorgang, 200 OK bei einer Aktualisierung, mit der Konfiguration (siehe OIDC-Konfiguration abrufen) und dem neuen ETag. Das Client-Geheimnis ist nicht in der Antwort enthalten. Wurde die Aktualisierung zu einer Entwurfsrevision, enthält der Body zusätzlich revision (der Entwurf); Konfiguration und ETag sind dann die live Werte.

Fehler

HTTP code Wann
404 not_found Die Verbindung existiert in dieser Umgebung nicht oder ist keine Unternehmensverbindung.
409 conflict Die Verbindung ist keine OIDC-Verbindung, sp_host weicht vom gespeicherten Host ab, oder eine Methode mit Geheimnis hat kein gespeichertes oder angegebenes Geheimnis.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein, die Konfiguration wurde parallel geändert, oder If-Match wurde vor dem ersten Schreibvorgang gesendet.
422 validation_failed Ein Feld verletzt die oben genannten Regeln; errors[] verweist auf das Feld (/issuer, /client_id, /client_auth_method, /client_secret, /client_secret_expires_at, /provider_profile, /entra_tenant_id, /sp_host).
428 precondition_required Die Konfiguration existiert, und der Header If-Match fehlt.
400 unknown_field Der Body enthält ein unbekanntes Feld.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung.
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

Bewahren Sie das Geheimnis in einer Datei auf, nicht in der Befehlszeile (oidc.json):

{"sp_host":"acme.eu1.keenauth.app","issuer":"https://idp.example.com","client_id":"keenauth-acme","client_auth_method":"client_secret_basic","client_secret":"<secret from the identity provider>"}

curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/oidc" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @oidc.json

keenauth connections oidc put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @oidc.json
keenauth connections oidc put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data @oidc-update.json --if-match '"6f1c…"'