マッピング設定を追加¶
POST /api/v1/login_mapping/field/add
概要¶
アイデンティティ属性から対象ワークスペースのロールへのシステムログインマッピングを作成します。
呼び出し前の準備と使用手順¶
まず実際のアイデンティティ属性名/値、アクティブなワークスペース、ロールUUIDを準備し、マッピングスイッチとモードを読んでスイッチとモードを確認してから作成します。成功するとルールスナップショットが返されるため、その後一覧でuuidを照合します。同じワークスペース、ソースフィールド名、ソースフィールド値に対して許可されるアクティブなシステムルールは1件のみです。複数ロールは同じtargetValues配列に格納します。ルールを保存しても、既存ユーザーに直ちにTokenが発行されたり、既存セッションが変更されたりすることはありません。実際のテストアイデンティティを使用し、以降の関連ログインで検証します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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取得または入力方法: アイデンティティプロバイダー/LDAPの実際のuserinfo属性定義から取得します。アカウントの直近ログイン後のアカウント詳細にあるcontent.attributesは、元のキーの確認に役立ちます。 |
| sourceValue | string | Y | 必須の文字列。最大256文字。完全一致で照合します。空文字列は属性の空文字列にのみ一致し、任意の値を表すものではありません。リスト属性は単一要素の値として入力します。 null許可: False 最大長: 256 例: 研发部取得または入力方法: 元のアイデンティティ属性の実際の値を使用します。アカウント詳細の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はアイデンティティサービスの元のuserinfoのトップレベルキーを読み取ります。大文字と小文字およびキー名は一致している必要があり、JSONPathやネストされたパスはサポートされません。アカウントのcustomAttributesはこの照合のソースではありません。アカウントのattributesを変更しても、アイデンティティサービスの次回のuserinfoは変わりません。sourceValueは文字列化された属性値と完全に一致し、正規表現や包含一致ではありません。属性がリストの場合、要素ごとに照合し、いずれかの要素がsourceValueと等しければ一致します。複数の一致ルールは同じワークスペース内で有効なロールをマージします。アイデンティティ側では安定した文字列属性を提供することを推奨します。数値はその文字列表現で照合し、真偽値は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/add'
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.id | integer または null | レコードの連番。作成スナップショットではnullになる場合があり、操作にはuuidを使用します。 |
| content.uuid | string | マッピングレコードのUUID。通常lgmp_プレフィックスが付きます。 |
| content.status | integer | ルールのステータス。アクティブは0です。一覧では3でフィルタされますが、履歴上の他のステータスが含まれる場合があります。実際のログインでの消費および変更/削除では0のみを処理します。 |
| content.creator | string | 作成者のアイデンティティ。Externalでは通常sysです。 |
| content.updator | string | 更新者のアイデンティティ。未更新の場合は空になることがあります。 |
| content.createAt | integer | 作成日時のUnix秒。 |
| content.deleteAt | integer | 削除日時のUnix秒。未削除の場合は通常-1です。 |
| content.updateAt | integer | 更新日時のUnix秒。未更新の場合は通常-1です。 |
| content.sourceField | string | 照合対象の元のuserinfoトップレベル属性名。 |
| content.sourceValue | string | 照合対象の属性文字列値。 |
| content.targetValues | 文字列配列 | 保存された対象ロールUUIDリスト。履歴上のリスト項目からロールが依然として有効であると直接断定することはできません。 |
| content.targetValues[] | string | 単一の対象ロールUUID。 |
| content.workspaceUUID | string | このルールの対象ワークスペースUUID。 |
| content.isSystem | integer または boolean | このモジュールはシステムマッピングであり、1またはtrueです。ワークスペースのカスタムルールではありません。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "lgmp_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"sourceField": "department",
"sourceValue": "研发部",
"targetValues": [
"readOnly"
],
"workspaceUUID": "wksp_example001",
"isSystem": 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.LoginMappingFieldAlreadyExists | 同じ対象ワークスペースに同じsourceFieldとsourceValueを持つアクティブなシステムルールが既に存在する | ワークスペースに同じマッピングフィールド名とフィールド値が既に存在します | 既存ルールを照会して変更するか、異なる属性と値を使用してください。このエラーはHTTP 404ですが、ルールが作成されなかったと誤認して無限に再試行しないでください。 |
| 406 | ft.InvalidRoleUuidBelongsWSKP | targetValuesに無効、削除済み、または対象ワークスペースの許可範囲に属さないロールUUIDが含まれている | 現在設定されているTargetValuesに無効なロールUUIDが存在します | 対象ワークスペースのロール一覧から有効なuuidを取得してください。別のワークスペースのカスタムロールをコピーすることはできません。 |
| 500 | ft.InternalServerError | データベース、サイト設定キャッシュ、監査、または未処理の履歴データの異常 | 内部エラー | traceIdを保持し、まずルールまたはスイッチを読み取って現在の状態を確認してください。データベースとキャッシュ/監査は同じトランザクションではないため、エラーが完全に未保存であることを証明するものではありません。 |