マッピングルールを作成¶
POST /api/v1/sso_mapping/field/add
概要¶
指定した SSO プロバイダーに対して、属性からロールへのマッピングを作成します。
呼び出し前の準備と使用手順¶
本グループの API は、特定の 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 を送信しないでください。 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/sso_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 を保持してください。 |