マッピング設定を追加¶
POST /api/v1/login_mapping/field/add
概要¶
このワークスペースのログイン属性からロールセットへのマッピングを作成します。
呼び出し前と使用手順¶
このグループは、現在のワークスペースにおける isSystem=false のデプロイメントプラン向けカスタムログイン属性マッピングを管理します。ssoUUID でアイデンティティプロバイダーをバインドする SAML マッピングや、External/Inner のシステムマッピングとは異なります。実際に有効にするには、さらにワークスペースで isOpenCustomMappingRule を有効にする必要があります。カスタムマッピングでスイッチを設定し、ログインポリシーを確認できます。保存/削除はルールのみを変更し、既存メンバーのロールを即時に変更せず、既存セッションも取り消しません。以降の LDAP/OIDC 共通ログインフローでは、実際の userinfo に基づいて再マッチングします。
マッチングでは userinfo のトップレベル属性を取得します。配列は要素ごとに str(value) で比較し、その他の値は Python の文字列表現で比較します。フィールドと値はデータベースの等値セマンティクス(大文字小文字/照合順序はデプロイ先データベースにより決定)を使用し、正規表現/包含検索やネストパス抽出は行いません。アイデンティティソースの安定した文字列のみを使用することを推奨します。複数のマッチングルールのロールは和集合を取り、その後で利用可能なロールをフィルタリングします。ワークスペースのカスタムスイッチが有効な場合、システムルールより優先されます。マッチした場合は通常ロールをリセットし、マッチしない場合は元の関連付けがクリアされる可能性があります。既存の Owner ロールには保護ロジックがあります。実際の権限は専用のテストアイデンティティで事前に検証してください。今回の HTTP 成功のみで、次回ログイン時のロールが正しいと判断しないでください。
同一ワークスペースの sourceField+sourceValue には、アクティブなカスタムルールを 1 件のみ許可します。保存成功時は true のみを返し、新しい UUID は直接返しません。その後、一覧でソースフィールド/ソース値により確認してください。一部の無効なロールがフィルタリングされた後でも成功する可能性があるため、targetValues と roleInfos を読み戻して確認する必要があります。[] はクリアコマンドではなく、ロールレコードがない場合は 404 になります。ヒットしたレコードがすべてソフト削除されたロールの場合、空のセットが保存される可能性があるため、利用可能な設定として扱わないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 アイデンティティソース管理者から実際の userinfo トップレベル属性名を取得します。正常にログインした後のアカウント attributes と照合できます。 |
| sourceValue | string | Y | 必須の文字列(256 文字以下)です。元の値で正確に入力することを推奨します。JSON 配列のテキストや正規表現ではありません。空文字列は現在一律には拒否されず、マッチするかどうかは実際の userinfo に依存します。 null を許可: False 最大長: 256 例: engineering取得または入力方法: その属性のログイン時の実際の値を取得します。配列属性の場合は、いずれか 1 つの要素の文字列値を使用します。 |
| 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/add' \
-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 | 対象/既存のマッピングロールセットに、一致する表示可能なロールレコードが 1 件もない([] を含む)。単一削除または一括削除の監査で旧ロールを解析した場合にも発生する可能性があります | 指定されたロールが見つからないか、ロールが削除されています | まずこのワークスペースのロール一覧とマッピング一覧で確認してください。未知のロールが一部混入している場合はフィルタリングされます。履歴上の空/一致なしのセットは、削除可能と直接仮定できません。管理者が修復した後に対処する必要があります。 |
| 500 | ft.InternalServerError | マッピング/ロール/データベースストレージまたはデータフォーマットで未捕捉の例外が発生 | 内部エラー | まず一覧でルールが保存済みか、および最終的な targetValues を確認し、その後で具体的なフィールドに対処してください。traceId を保持してください。 |