マッピングルールを作成(旧互換インターフェース)¶
POST /api/v1/saml/mapping/field/add
概要¶
指定した SSO プロバイダーの属性からロールへのマッピングを作成します。
呼び出し前の確認と使用手順¶
これは旧アドレス互換インターフェースであり、現在のソースコードでも実際に登録されています。過去の「2026-05-31 廃止」というコメントは、現在リクエストが禁止されていることを意味するものではありません。新規接続ではマッピングルールを作成を優先して使用してください。旧パスは同じコントローラー/リクエストフィールド/レスポンスを踏襲しており、saml プレフィックスのために OIDC が除外されることはありません。
本グループは、特定の SSO プロバイダーのログイン attributes を現在のワークスペースのロールにマッピングするものであり、デプロイメントプランの LDAP/OIDC の custom_login_mapping やシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping(本グループでは set_disable)を有効にする必要があり、SSO 設定自体も有効になっている必要があります。
属性名のマッチングは小文字に変換して比較されますが、値は正規表現/包含マッチングではありません。文字列配列は値ごとにマッチングされます。配列でないオブジェクト/数値/null などはまず json.dumps で文字列に変換されますが、配列の要素は一律に文字列へ変換されるわけではありません。そのため、アイデンティティソースで安定した文字列属性および文字列配列を使用することを推奨します。複数のロールがヒットした場合は和集合が取られます。SSO のマッピングを有効にした後、ルールがない/マッチングしない場合、アカウントがこのワークスペースへ入ることを禁止でき、以降のログイン/切り替え時に古い関連付けが削除されます。単純にデフォルトロールを追加するものではありません。書き込み後は非同期でワークスペースとメンバーのキャッシュを更新するため、既存の SSO セッションの以降のアクセスに影響する可能性があり、次回ログイン時にのみ有効になるとは保証できません。
同一プロバイダー内でフィールド/値の組み合わせは一意です。作成してもプロバイダーのマッピングスイッチは自動的に有効になりません。まずルールを設定・検証してから有効にしてください。成功時は true のみが返され、その後リストから新しい UUID を取得できます。入力したロールはフィルタリングされます。保存後は targetValues/roleInfos と ssoInfo を照合してください。送信後はキャッシュ更新タスクが投入されます。投入に失敗した場合は 500 になる可能性がありますが、ルールはすでに保存されています。むやみに重複作成しないでください。本グループは SSO 設定変更メールを送信せず、共有 SSO の create/modify の needNotify パラメーターを本ページに適用することもありません。
リクエストヘッダー¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象のワークスペースの API Key 管理から、この操作権限のある OpenAPI Key を取得します。 |
Body リクエストパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| targetValues[*] | string | 文字列。表示名ではなく、ネストしたオブジェクトは送信しません。現在、要素の形状は一律に強く型チェックされていません。 例: general取得または入力方法: 本ワークスペースで参照可能な単一のロール UUID/システム識別子。 |
|
| sourceField | string | Y | 必須。空でないことを推奨します。マッチング時にフィールド名は大文字小文字を区別しませんが、同名チェックは依然としてデータベースの等値セマンティクスに従って判定されます。ドットパスはサポートされません。新規追加には一律の長さ上限宣言はありませんが、変更は≤256、格納列は256であり、いずれも≤256 に収めることを推奨します。 null を許可: False 例: groups取得または入力方法: アイデンティティプロバイダーの管理者から実際の attributes トップレベルフィールド名を提供してもらいます。 |
| sourceValue | string | Y | 必須。空でないことを推奨します。ワイルドカード/正規表現ではありません。新規追加では長さが宣言されていませんが、変更は≤256、格納列は256であり、いずれも≤256 に収めることを推奨します。 null を許可: False 例: engineering取得または入力方法: 属性の実際の文字列、または文字列配列内の単一要素を指定します。配列全体のテキストを記入しないでください。 |
| ssoUUID | string | Y | 新規追加では必須と宣言されています。変更では任意と宣言されていますが、実装では省略値 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/add' \
-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 を保持してください。 |