マッピングルールの変更(旧互換インターフェース)¶
POST /api/v1/saml/mapping/field/{fdmp_uuid}/modify
概要¶
SSO 属性マッピングとプロバイダーバインディングを一括更新します。
呼び出し前の確認と使用手順¶
これは旧アドレスの互換インターフェースであり、現在のソースコードでも引き続き実際に登録されています。過去の「2026-05-31 廃止」というコメントは、現在リクエストが禁止されていることを示すものではありません。新規連携ではマッピングルールの変更を優先して使用してください。旧パスは同じコントローラー、リクエストフィールド、レスポンスを踏襲しており、saml プレフィックスを理由に OIDC が除外されることはありません。
本グループでは、特定の SSO プロバイダーのログイン attributes を現在のワークスペースのロールにマッピングします。これはデプロイメントプランの LDAP/OIDC における custom_login_mapping およびシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping(本グループの set_disable)を有効にする必要があり、SSO 設定自体も有効になっている必要があります。
属性名のマッチングは小文字で比較され、値は正規表現/部分一致ではありません。文字列配列は各値を個別にマッチングします。配列でないオブジェクト、数値、null などはまず json.dumps で文字列に変換されますが、配列の要素は一律に文字列へ変換されません。そのため、アイデンティティソースで安定した文字列属性および文字列配列を優先して使用してください。複数のロールがヒットした場合は和集合を取ります。SSO のマッピングを有効にした後、ルールがない/一致しない場合、アカウントがこのワークスペースへ入ることを禁止でき、その後のログイン/切り替え時に古い関連付けを削除します。単にデフォルトロールを追加するものではありません。書き込み後はワークスペースとメンバーのキャッシュを非同期で更新するため、既存の SSO セッションの以降のアクセスに影響する可能性があり、次回ログイン時のみ有効になるとは保証できません。
ssoUUID および 3 つのマッピングフィールドを明示的に送信する必要があります。全体を上書きし、フィールド単位でマージすることはありません。ssoUUID を省略すると、現在は None が非 NULL カラムに書き込まれて 500 が発生します。省略可能という宣言を「保持される」と解釈しないでください。ssoUUID を変更しても、新しいプロバイダーが有効であることを証明するものではありません。先に本ワークスペースの SSO リストを確認してください。入力ロールはフィルタリングされます。保存後は targetValues/roleInfos と ssoInfo を確認してください。送信後はキャッシュ更新タスクが投入され、ディスパッチに失敗すると 500 になる可能性がありますが、ルールはすでに保存されています。やみくもに重複作成しないでください。本グループでは SSO 設定変更メールを送信しません。共有 SSO の create/modify における needNotify パラメーターをこのページに適用しないでください。
ルートパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| fdmp_uuid | string | Y | プロバイダー UUID やデプロイメントプランのカスタム lgmp_ ではありません。 例: fdmp_example取得または入力方法: マッピングリストの content.data[].uuid から本ワークスペースの fdmp_ を取得します。 |
リクエストヘッダー¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| targetValues[*] | string | 文字列であり、表示名ではありません。ネストされたオブジェクトは送信しません。現在、要素の形状に対して統一的な厳密型チェックは行われていません。 例: general取得または入力方法: 本ワークスペースで表示可能な単一ロールの UUID/システム識別子。 |
|
| sourceField | string | Y | 必須。空でないことを推奨します。マッチング時、フィールド名は大文字小文字を区別しませんが、同名チェックはデータベースの等値セマンティクスによって決まります。ドットパスはサポートされません。新規追加時には統一的な長さ上限の宣言がなく、変更時は 256 以下、格納カラムは 256 です。いずれも 256 以下に抑えることを推奨します。 null 許可: False 最大長: 256 例: groups取得または入力方法: アイデンティティプロバイダー管理者から提供される実際の attributes トップレベルフィールド名を指定します。 |
| sourceValue | string | Y | 必須。空でないことを推奨します。ワイルドカード/正規表現ではありません。新規追加時は長さが宣言されておらず、変更時は 256 以下、格納カラムは 256 です。いずれも 256 以下を推奨します。 null 許可: False 最大長: 256 例: engineering取得または入力方法: 属性の実際の文字列、または文字列配列内の単一要素を指定します。配列全体のテキストを入力しないでください。 |
| ssoUUID | string | 新規追加時は必須と宣言されています。変更時は省略可能と宣言されていますが、実装では省略値 None で旧 ssoUUID を上書きするため、通常の送信ではデータベース 500 が発生する可能性があります。現在/新しいターゲットを明示的に再設定する必要があります。現在、追加/変更時に SSO の存在や所属ワークスペースは強制検証されません。保存に成功してもターゲットが有効であることを証明するものではありません。他のワークスペースの UUID や偽の UUID を送信しないでください。 null 許可: False 最大長: 48 例: sso_example取得または入力方法: SSO 設定リストから現在のワークスペースのプロバイダー uuid を取得し、SAML または OIDC を実際の設定に応じて選択します。 |
|
| targetValues | array | Y | 必須の配列。空でないことを推奨します。一部の未知の/クロスワークスペースのロールはフィルタリングされ、ステータス 0/2 は保持されます。[] または表示可能なレコードがまったくない場合は NotFoundRole を返します。ステータス 2 の保存は現在利用可能であることを保証せず、リストの roleInfos には 0 のみが表示されます。すべてのターゲットが論理削除されていてもレコードが存在する場合、空の集合にフィルタリングされることがあり、有効なマッピングとして扱われません。 例: ["general"]取得または入力方法: 現在のワークスペースのロールリストから表示可能なロール識別子を取得します。例: general/readOnly/カスタム role_。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/saml/mapping/field/fdmp_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"ssoUUID":"sso_example","sourceField":"groups","sourceValue":"engineering","targetValues":["general"]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は true。マッピングエンティティやログイン結果は返しません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメーター解析失敗 | パラメーターの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | ssoUUID/sourceField/sourceValue/targetValues を完全なオブジェクトとして送信してください。 |
| 404 | ft.SamlMappingFieldAlreadyExists | 本ワークスペースに同じ ssoUUID+sourceField+sourceValue の非削除マッピングが既に存在します(変更時は自身を除外) | ワークスペースに同じマッピングフィールド名とフィールド値が既に存在します | 新しい組み合わせに変更するか、既存の UUID を更新してください。HTTP が 404 であることに注意してください。 |
| 404 | ft.NotFoundRole | 入力ロールまたは旧マッピングのターゲット集合に、本ワークスペースで表示可能なロールレコードがありません([] を含む)。変更/削除の監査でも発生する可能性があります | 指定されたロールが見つからないか、ロールが削除されています | ロールリストから現在の入力/旧ターゲットを確認し、空の集合をクリア成功として扱わないでください。過去の破損したルールは管理者が修復してから処理してください。 |
| 500 | ft.InternalServerError | 保存する JSON の形状、データベース、または送信後のタスクディスパッチで捕捉されていない例外が発生しました | 内部エラー | データベースはコミット済みでキャッシュタスクのディスパッチが失敗している可能性があります。まずリストからルール/SSO スイッチを読み戻してから処理し、traceId を保持してください。 |
| 404 | ft.SamlMappingNoExists | fdmp_uuid に本ワークスペースの非削除マッピングレコードがありません | 指定された Saml Mapping が見つかりません | 本ワークスペースのマッピングリストから fdmp_ UUID を再取得してください。sso_ や lgmp_ ではありません。 |