マッピング設定の変更¶
POST /api/v1/login_mapping/field/{lgmp_uuid}/modify
概要¶
このワークスペースのカスタムログインマッピングルールを一括更新します。
呼び出し前の確認と使用手順¶
このグループは、現在のワークスペースにおける isSystem=false のデプロイメントプラン用カスタムログイン属性マッピングを管理します。ssoUUID で ID プロバイダーをバインドする SAML マッピングや、External/Inner のシステムマッピングとは異なります。実際に有効になるには、ワークスペースで isOpenCustomMappingRule を有効化する必要があります。カスタムマッピング でスイッチを設定し、ログインポリシーを確認できます。保存/削除はルールのみを変更し、既存メンバーのロールを即時に変更せず、既存セッションも取り消しません。以降の LDAP/OIDC 共有ログインフローでは、実際の userinfo に基づいて再マッチングします。
マッチングでは userinfo のトップレベル属性を取得します。配列は要素ごとに str(value) で比較し、その他の値は Python の文字列形式で比較します。フィールドと値はデータベースの等値セマンティクスを使用します(大文字小文字/照合順序はデプロイメントのデータベースによって決まります)。正規表現/包含判定/ネストパス抽出は行いません。ID ソースの安定した文字列のみを使用することを推奨します。複数のマッピングルールでロールを和集合として取得し、その後、利用可能なロールでフィルタリングします。ワークスペースのカスタムスイッチが有効な場合、システムルールより優先されます。一致する場合、通常はロールをリセットします。一致しない場合、既存の関連付けをクリアする可能性があります。既存の Owner ロールには保護ロジックがあります。実際の権限は、専用のテスト ID であらかじめ検証してください。今回の HTTP 成功のみで、次回ログイン時のロールが正しいと判断しないでください。
3 つの業務フィールドはすべて完全に送信する必要があります。targetValues は古いロールセットを全体置換し、追加/マージは行いません。UUID は変更されません。このカスタムルールを system に変換したり、他のワークスペースへ移動したりすることはサポートされていません。一部の無効なロールがフィルタリングされた後でも成功する可能性があるため、targetValues と roleInfos を読み戻して確認する必要があります。[] はクリアコマンドではありません。ロールレコードがないため 404 を返します。一致したレコードがすべて論理削除済みロールの場合、空のセットが保存される可能性があるため、利用可能な設定として扱わないでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| lgmp_uuid | string | Y | ロール、SSO プロバイダー、または SAML の fdmp_ マッピング UUID ではありません。 例: lgmp_example取得/入力方法: ルール一覧 の content.data[].uuid から、現在のワークスペースの lgmp_ レコードを取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得/入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| targetValues[*] | string | 単一の文字列であり、ロールの表示名ではありません。配列要素には統一された強い型制約がないため、不正な形状は 500 になる可能性があります。オブジェクトやネストした配列を送信しないでください。 例: general取得/入力方法: このワークスペースで表示可能な単一のロール UUID またはシステムロール識別子を指定します。 |
|
| sourceField | string | Y | 必須の文字列です。空でない値を使用し、大文字小文字を実際の属性と一致させることを推奨します。ドットパス走査/ワイルドカードはサポートしていません。API 宣言は 256 文字以下ですが、現在の保存列は 128 文字です。データベースエラーを避けるため 128 文字以下に抑えることを推奨します。自動 trim は行われません。 null を許可: False 最大長: 256 例: department取得/入力方法: デプロイメントの LDAP/OIDC ID ソース管理者から実際の userinfo トップレベル属性名を取得します。ログイン成功後のアカウント attributes と照合できます。 |
| sourceValue | string | Y | 必須の文字列(256 文字以下)で、元の値を正確に入力することを推奨します。JSON 配列のテキストや正規表現ではありません。空文字列は現在一律には拒否されず、一致するかどうかは実際の userinfo に依存します。 null を許可: False 最大長: 256 例: engineering取得/入力方法: その属性のログイン時の実際の値を取得します。配列属性の場合は、いずれかの要素の文字列値を使用します。 |
| targetValues | array | Y | 必須の配列で、空でないことを推奨します。不明なロール/他のワークスペースのロールはフィルタリングされます。ステータス 0/2 は保持され、すべて存在しない場合/[] の場合は NotFoundRole を返します。ステータス 2/削除済みロールは、以降のログインで有効な権限を取得しません。保存時の true を、すべてのロールが有効になったとみなさないでください。現在のワークスペースのカスタムエントリには、External システムマッピングの Owner 禁止は適用されていません。クライアントは実際の認可用途に応じて対象ロールを選択してください。 例: ["general"]取得/入力方法: 対象ワークスペースのロール一覧から、現在利用可能なロール UUID/システムロール識別子(general/readOnly やカスタム role_ など)を選択します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/login_mapping/field/lgmp_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"sourceField":"department","sourceValue":"engineering","targetValues":["general"]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は true です。新規エンティティ/UUID やロール一覧は返されません。再度 list で確認してください。 |
{
"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 オブジェクトではありません | 一部の JSON ファイルの形式が正しくありません | sourceField/sourceValue/targetValues を含む完全なオブジェクトを送信してください。 |
| 404 | ft.SamlMappingFieldAlreadyExists | 現在のワークスペースのカスタムルールに、同じ sourceField+sourceValue の組み合わせが既に存在します(変更時は自身を除外) | ワークスペースに同じマッピングフィールド名とフィールド値が既に存在します | 組み合わせを変更するか、既存の UUID を変更してください。履歴上のエラーコードは 404 で Saml プレフィックスを含みますが、引き続きこのカスタムグループに使用されます。 |
| 404 | ft.NotFoundRole | 対象/既存のマッピングロールセットに一致する可視ロールレコードがありません([] を含む)。単一削除または一括削除の監査で旧ロールを解析する際にも発生する可能性があります | 指定されたロールが見つからないか、ロールが削除されています | まずこのワークスペースのロール一覧とマッピング一覧で確認してください。不明なロールが一部混在する場合はフィルタリングされます。履歴上の空/一致なしのセットは、そのまま削除可能と仮定できません。管理者が修復した後に処理してください。 |
| 500 | ft.InternalServerError | マッピング/ロール/データベース保存またはデータフォーマットで未キャッチの例外が発生 | 内部エラー | まず一覧でルールが保存済みか、および最終的な targetValues を確認し、その後、具体的なフィールドに対して処理してください。traceId を保持してください。 |
| 404 | ft.LoginMappingNoExists | 単一 UUID が、このワークスペースの isSystem=false かつ status=0 のマッピングに属していません | 指定された Login Mapping が見つかりません | このワークスペースの一覧から lgmp_ UUID を再取得してください。システムルールまたは非アクティブなレコードは、この単一項目エントリでは操作できません。 |