Attributzuordnungen einer Verbindung ersetzen

PUT /v1/connections/{connection_id}/attribute-mappings · Berechtigung connections:write

Ersetzt die vollständige Attributzuordnungsliste einer Unternehmensverbindung. Die Reihenfolge der Regeln spielt keine Rolle; die Antwort ist nach Ziel sortiert. If-Match ist erforderlich: Ohne diesen Header schlägt die Anfrage mit 428 fehl; wurde die Liste seit dem Lesen geändert (oder passt der Wert nicht), schlägt sie mit 412 fehl und es wird nichts geschrieben. Das Senden derselben Liste schreibt nichts. Die Änderung gilt ab der nächsten Anmeldung und macht den letzten bestandenen Verbindungstest nicht ungültig. Der Schreibvorgang wird als connection.attribute_mappings_replaced protokolliert (hinzugefügte, entfernte und geänderte Ziele); Attributwerte aus Anmeldungen werden niemals im Audit-Log gespeichert.

Anfrage

Feld Typ Pflicht Beschreibung
connection_id Pfad ja ID der Unternehmensverbindung (conn_…).
If-Match Header ja Der ETag aus dem letzten Lesevorgang. Fehlt: 428; veraltet: 412.
attribute_mappings Array ja Die vollständige neue Liste, höchstens 28 Regeln.
attribute_mappings[].target String ja email (in jeder Liste erforderlich), given_name, family_name, name, locale, zoneinfo, phone, groups oder user_metadata.<key> (Schlüssel [a-z0-9_]{1,40}; registrierte OIDC-Claim-Namen und das Präfix idp_ sind nicht erlaubt; höchstens 20 Schlüssel). Eine Regel pro Ziel. app_metadata kann per Zuordnung nicht geschrieben werden.
attribute_mappings[].source_name String ja 1–512 Byte, keine Steuer- oder bidirektionalen Zeichen, kein führendes oder nachgestelltes Leerzeichen.
attribute_mappings[].source_name_format String | null nein SAML-NameFormat (absolute URI). Ein Quellname kann nur mit einem einzigen Format gelesen werden.
attribute_mappings[].overwrite String ja always, if_empty oder never.
attribute_mappings[].profile String nein Name der Voreinstellung; ohne Angabe generic.

Antwort

200 OK mit der gespeicherten Liste (siehe Attributzuordnungen abrufen) und dem neuen ETag.

Fehler

HTTP code Wann
404 not_found Die Verbindung existiert in dieser Umgebung nicht oder ist keine Unternehmensverbindung.
409 conflict Das Protokoll der Verbindung kennt keine Attributzuordnungen (LDAP).
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version überein, oder die Liste wurde gleichzeitig geändert.
422 validation_failed Eine Regel verletzt die oben genannten Regeln. Jede fehlerhafte Regel ist ein Eintrag in errors[], der auf /attribute_mappings/<index>/<field> verweist, oder auf /attribute_mappings für Listenregeln (email_required, too_many_metadata_keys).
428 precondition_required Der Header If-Match fehlt.
400 unknown_field Der Anfrageninhalt enthält ein unbekanntes Feld.
401 unauthenticated Das Zugangsdatum fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Dem Zugangsdatum fehlt 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

curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "6f1c…"' \
  -d '{"attribute_mappings":[{"target":"email","source_name":"email","overwrite":"always"},{"target":"user_metadata.department","source_name":"department","overwrite":"if_empty"}]}'

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