コンテンツにスキップ

マッピングルールの変更



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_ ではありません。

フィードバック

このページは役に立ちましたか?