マッピングルールの変更¶
POST /api/v1/sso_mapping/field/{fdmp_uuid}/modify
概要¶
SSO 属性マッピングとプロバイダーバインディング全体を更新します。
呼び出し前の準備と使用手順¶
本グループでは、特定の SSO プロバイダーのログイン attributes を現在のワークスペースのロールにマッピングします。これはデプロイメントプランの LDAP/OIDC の custom_login_mapping およびシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping を有効にする必要があります(本グループの set_disable)。SSO 設定自体も有効になっている必要があります。
属性名のマッチングは小文字で比較されます。値は正規表現/包含一致ではありません。文字列配列は値ごとに照合されます。配列でないオブジェクト、数値、null などは、まず json.dumps で文字列に変換されます。配列要素は一律に文字列へ変換されないため、ID ソースで安定した文字列属性と文字列配列の使用を優先してください。複数のロールが一致した場合は和集合を取ります。SSO のマッピングを有効にした後、ルールがない場合や一致しない場合は、アカウントがこのワークスペースへアクセスすることを禁止でき、以降のログイン/切り替え時に古い関連付けを削除します。単にデフォルトロールを追加するものではありません。書き込み後、ワークスペースとメンバーのキャッシュを非同期で更新します。既存の SSO セッションの以降のアクセスに影響する可能性があり、次回ログイン時のみ有効になるとは保証できません。
ssoUUID と 3 つのマッピングフィールドを明示的に送信する必要があります。フィールド単位でマージするのではなく、全体を上書きします。現在、ssoUUID を省略すると None が NOT 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 を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| targetValues[*] | string | 文字列。表示名ではなく、ネストしたオブジェクトは送信しません。現在、要素の形状に対する統一的な厳密型チェックはありません。 例: general取得または入力方法: 本ワークスペースで参照可能な単一ロールの UUID/システム識別子。 |
|
| sourceField | string | Y | 必須。空でない値を推奨します。照合時、フィールド名は大文字と小文字を区別しませんが、同名チェックは引き続きデータベースの等値セマンティクスによって決まります。ドットパスはサポートされません。新規作成には統一された長さ上限の宣言がありませんが、変更時は 256 以下、格納カラムは 256 です。いずれも 256 以下に抑えることを推奨します。 null 許可: False 最大長: 256 例: groups取得または入力方法: ID プロバイダー管理者から提供される実際の attributes のトップレベルフィールド名を指定します。 |
| sourceValue | string | Y | 必須。空でない値を推奨します。ワイルドカード/正規表現ではありません。新規作成では長さが宣言されておらず、変更時は 256 以下、格納カラムは 256 です。いずれも 256 以下に抑えることを推奨します。 null 許可: False 最大長: 256 例: engineering取得または入力方法: 属性の実際の文字列、または文字列配列内の単一要素を指定します。配列全体のテキストを入力しないでください。 |
| ssoUUID | string | 新規作成では必須と宣言されています。変更ではオプションと宣言されていますが、実装では省略値 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/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_ ではありません。 |