接続の属性マッピングを置き換える

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

企業接続の属性マッピング一覧を全体置換します。ルールの順序は問いません。レスポンスはターゲット順に並びます。If-Match は必須です。指定がないとリクエストは 428 で失敗します。読み取り後に一覧が変更されている場合（または値が一致しない場合）は 412 で失敗し、何も書き込まれません。同じ一覧を送信しても書き込みは行われません。変更は次回のサインインから適用され、直近の成功した接続テストは無効になりません。書き込みは connection.attribute_mappings_replaced として監査されます（追加、削除、変更されたターゲット）。サインイン時の属性値が監査ログに書き込まれることはありません。

リクエスト

フィールド 型 必須 説明
connection_id パス はい 企業接続の ID（conn_…）。
If-Match ヘッダー はい 直近の読み取りで得た ETag。欠落時は 428、古い場合は 412。
attribute_mappings 配列 はい 新しい完全なリスト。最大 28 ルール。
attribute_mappings[].target 文字列 はい email（すべてのリストで必須）、given_name、family_name、name、locale、zoneinfo、phone、groups、または user_metadata.<key>（キーは [a-z0-9_]{1,40}。登録済みの OIDC クレーム名と idp_ 接頭辞は使用不可。最大 20 キー）。ターゲットごとに 1 ルール。マッピングで app_metadata は書き込めません。
attribute_mappings[].source_name 文字列 はい 1〜512 バイト。制御文字や双方向文字を含まず、先頭または末尾に空白を含まないこと。
attribute_mappings[].source_name_format 文字列 | null いいえ SAML の NameFormat（絶対 URI）。1 つのソース名は 1 つの形式でのみ読み取れます。
attribute_mappings[].overwrite 文字列 はい always、if_empty、または never。
attribute_mappings[].profile 文字列 いいえ プリセット名。省略時は generic。

レスポンス

保存済みのリスト（属性マッピングを取得するを参照）と新しい ETag を含む 200 OK。

エラー

HTTP code 発生条件
404 not_found 接続がこの環境に存在しないか、企業接続ではありません。
409 conflict 接続のプロトコルには属性マッピングがありません（LDAP）。
412 precondition_failed If-Match が現在のバージョンと一致しないか、リストが同時に変更されました。
422 validation_failed ルールが上記の規則に違反しています。違反した各ルールは errors[] の 1 項目となり、/attribute_mappings/<index>/<field> を指します。リスト全体のルール（email_required、too_many_metadata_keys）は /attribute_mappings を指します。
428 precondition_required If-Match ヘッダーがありません。
400 unknown_field リクエストボディに未知のフィールドがあります。
401 unauthenticated 資格情報がない、無効、または失効しています。
403 insufficient_permissions 資格情報に必要な権限がありません。
429 rate_limited レート制限を超えました。Retry-After の期間を待ってから再試行してください。
503 service_unavailable 依存先が一時的に利用できません。Retry-After の期間を待ってから再試行してください。

例

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…"'