マッピング設定の変更¶
POST /api/v1/login_mapping/field/{lgmp_uuid}/modify
概要¶
システムログインマッピングのソース属性、ターゲットワークスペース、ロールを完全に更新します。
呼び出し前の準備と使用手順¶
まずシステムログインマッピング一覧からルールを読み取り、バックアップしてください。sourceField、sourceValue、targetValues は必須です。workspaceUUID は任意と宣言されていますが、実際にも必須です。ロールのみを変更する際に旧ワークスペースを自動的に保持することはサポートされません。別のアクティブなワークスペースへ変更できますが、ロールは新しいワークスペースの有効範囲に属している必要があります。targetValues は完全なターゲットで置き換えられ、以前のリストとはマージされません。同じ新しいワークスペース/ソース属性の組み合わせは、他のシステムルールと競合できません。変更は以降のログインに影響します。ワークスペースを移行する前に、GlobalValid などのモードがユーザーの元の直接関係をクリアするかどうかを確認してください。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| lgmp_uuid | string | Y | アクティブなシステムマッピングの UUID です。ワークスペース UUID ではありません。 例: lgmp_example001取得または入力方法: システムログインマッピング一覧 の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを使用し続けることはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用しており、例の署名アルゴリズムと対応しています。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w の資格情報を使用でき、書き込み API では w の資格情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号です。失敗時の再送でも新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字のメソッド、nonce、元の完全なパス、timestamp、元の UTF-8 リクエストボディをスペースで結合し、HMAC-SHA256 を実行して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従い、対応する SK を使用して計算します。完全に実行可能なテンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイト設定の署名有効時間枠内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| targetValues[*] | string | 単一の有効なロール UUID 文字列です。異なるワークスペースのカスタムロールを混在させることはできず、owner は拒否されます。 例: readOnly取得または入力方法: ターゲットワークスペースのワークスペースロール一覧 から単一のロール uuid を取得します。 |
|
| sourceField | string | Y | 必須のトップレベル属性名です。最大 40 文字で、大文字と小文字を区別します。アカウント標準フィールドの別名や JSONPath ではありません。空でないことを推奨します。 null 許可: False 最大長: 40 例: department取得または入力方法: ID プロバイダー/LDAP の実際の userinfo 属性定義から取得します。アカウントの直近ログイン後のアカウント詳細 の content.attributes は、元のキーの確認に役立ちます。 |
| sourceValue | string | Y | 必須の文字列です。最大 256 文字で、完全一致します。空文字列は属性の空文字列にのみ一致し、任意の値を表すものではありません。リスト属性の場合は個々の要素値を入力します。 null 許可: False 最大長: 256 例: 研发部取得または入力方法: 元の ID 属性の実際の値を使用します。アカウント詳細 の content.attributes の対応するキー、または IdP/LDAP 属性で確認します。 |
| targetValues | array | Y | 必須の完全なロール配列です。owner を含めることはできず、null は無効です。[] は保存できますが、ターゲットの有効なロールがありません。これを安全な「ルールの無効化」方法として扱わないでください。最終的な権限処理はログインモードによって異なります。事前に重複を除去し、空でないロールリストを使用することを推奨します。 例: ["readOnly"]取得または入力方法: ワークスペースロール一覧 から workspaceUUID に基づいて、そのワークスペースで使用可能なロール uuid を取得します。 |
| workspaceUUID | string | Y | ターゲットのアクティブワークスペース UUID です。変更の宣言では任意とされていますが、現在の実装には旧値へのフォールバックがないため、実際にも明示的に指定する必要があります。 null 許可: False 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid から取得し、そのワークスペースに基づいてロールを読み取ります。 |
パラメータの補足説明¶
認証方式はExternal API 署名認証を参照してください。本モジュールはサイトのシステムログインマッピング(isSystem=1)を管理し、OIDC/LDAP など共有ログインマッピング経路を使用するサードパーティログインで使用されます。ワークスペースのカスタムマッピングや独立した SAML 設定 API ではありません。設定の保存によって既存ユーザーのすべての権限が即時に一括再計算されるわけではなく、後続の関連ログイン時にモードに従って処理されます。
sourceField は ID サービスの元の userinfo のトップレベルキーを読み取ります。大文字と小文字およびキー名は一致している必要があり、JSONPath やネストされたパスはサポートされません。アカウントの customAttributes はこのマッチングのソースではありません。アカウントの attributes を変更しても、ID サービスの次回の userinfo は変わりません。sourceValue は文字列化された属性値と完全に一致し、正規表現や部分一致ではありません。属性がリストの場合は要素ごとにマッチングし、いずれかの要素が sourceValue と等しければ一致します。複数のマッチングルールは同じワークスペース内で有効なロールをマージします。ID 側では安定した文字列属性を提供することを推奨します。数値はその文字列表現でマッチングし、ブール値は True/False、null は None、オブジェクトは JSON ではなく内部文字列形式でマッチングします。オブジェクト値でルールを構築することは推奨しません。
システムマッピングが有効で、ターゲットワークスペースのカスタムマッピングが無効な場合: ValidOnFirstLogin は、履歴上の直接ワークスペース関連付けを一切持たないアカウントにのみシステムルールを適用します(履歴には削除済みの関連付けも含まれます)。これは今回アカウントが新規作成されたかどうかだけを判定するものではありません。GlobalValid は、関連するログインのたびにルールに従って直接ロールを置き換え、一致しない場合は直接メンバー/ロール関係を削除できます。Append は一致したシステムロールのみを追加し、一致しない場合でも元の直接関係をクリアしません。ワークスペースでカスタムマッピングが有効な場合、そのワークスペースではカスタムルールに従って置き換え/不一致時のクリーンアップが優先して実行され、システムの Append や初回モードの保持セマンティクスを適用することはできません。システムスイッチをオフにしても、ワークスペースのカスタムルールは同時にオフになりません。既存の直接 Owner ロールはマッチング処理中に保持され、本モジュールを通じて新たに Owner を付与することはありません。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスと管理者が割り当てた External API AK/SK に置き換えてください。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/login_mapping/field/lgmp_example001/modify'
query = {}
data = {'workspaceUUID': 'wksp_example001', 'sourceField': 'department', 'sourceValue': '研发部', 'targetValues': ['readOnly']}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200、application/json の統一エンベロープです。External は declaration を自動注入しません。リストのページネーションは content.pageInfo にあります。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 変更成功時は true です。ルールの詳細は返しません。uuid を指定して一覧から再読み取りしてください。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
確認済みのルールとリクエストエラーを表に示します。通常のデータベース/キャッシュ/監査の異常は最終的に 500 ft.InternalServerError になります。設定がコミットされた後に後続のエラーが発生する可能性があるため、まず現在の状態を読み取ってから再試行してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答の説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | パラメータ表に従って JSON オブジェクトを送信してください。 |
| 401 | ft.WKSPNotExistOrReleased | ターゲット workspaceUUID がアクティブなワークスペースに対応していない、または変更時に実際に必須のこのパラメータを省略している | ワークスペースが存在しないか、解放済みです | ワークスペース一覧からアクティブな uuid を取得し、変更リクエストに明示的に含めてください。 |
| 400 | ft.LoginMappingNotSupportSetOwner | targetValues に owner が含まれています | 所有者ロールへのマッピングはサポートされていません | 正式な Owner 引き継ぎフローで処理してください。本 API は許可された他のロールのみをマッピングします。 |
| 404 | ft.LoginMappingNoExists | UUID が存在しない、削除済み、アクティブな status=0 ではない、またはシステムマッピングではない | 指定された Login Mapping が見つかりません | 本モジュールのシステムマッピング一覧から有効な uuid を再選択してください。ワークスペースのカスタムルール UUID は使用しないでください。 |
| 404 | ft.LoginMappingFieldAlreadyExists | 同じターゲットワークスペースに同じ sourceField と sourceValue を持つアクティブなシステムルールが既に存在します | ワークスペースに同じマッピングフィールド名とフィールド値が既に存在します | 既存ルールを検索して変更するか、異なる属性と値を使用してください。このエラーの HTTP は 404 であり、ルールが未作成だと誤認して無制限に再試行しないでください。 |
| 406 | ft.InvalidRoleUuidBelongsWSKP | targetValues に無効、削除済み、またはターゲットワークスペースの許可範囲に属さないロール UUID が含まれています | 現在設定されている TargetValues に無効なロール UUID が存在します | ターゲットワークスペースのロール一覧から有効な uuid を取得してください。別のワークスペースのカスタムロールをコピーすることはできません。 |
| 500 | ft.InternalServerError | データベース、サイト設定キャッシュ、監査、または未処理の履歴データの異常 | 内部エラー | traceId を保持し、まずルールまたはスイッチを読み取って現在の状態を確認してください。データベースとキャッシュ/監査は同一トランザクションではないため、エラーが完全に未保存であることを証明するものではありません。 |