スイッチ状態設定¶
POST /api/v1/login_mapping/set_disable
概要¶
サイトのシステムログインマッピングのマスタースイッチと適用モードを設定します。
呼び出し前の確認と使用手順¶
これはスイッチとモードの完全書き込みであり、部分更新ではありません。isDisable と type は常に明示的に指定することを推奨します。isDisable を省略するとデフォルトの 0(有効)が使用され、type を省略すると GlobalValid にリセットされます。{} を送信しても GlobalValid が有効になるため、照会や既存設定の維持には使用できません。まずマッピングスイッチとモードで旧値を保存し、そのうえでモードが既存ユーザーの次回ログインに与える影響を評価してください。isDisable=true はシステムルールのみを無効化し、ワークスペースのカスタムマッピングは同時に無効化せず、既存のロール/Token も即座に取り消しません。保存後にスイッチを読み戻し、管理下のテスト用 ID で後続のログインを検証してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒文字列を生成します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| isDisable | boolean | 省略可能なブール値。省略時は実際には整数 0(有効)が使用され、元の値は保持されません。null は不正です。 null 許可: False 選択可能な値: [True, False] 例: false取得または入力方法: true を渡すとシステムマッピングを無効化し、false で有効化します。変更しない場合は、先にスイッチを読み取り、現在値を明示的に設定し直してください。 |
|
| type | string | 省略可能な文字列。省略時はデフォルトの GlobalValid となり、以前のモードは保持されません。ValidOnFirstLogin は過去のワークスペース関連付けに基づいて初回ログインを判定します。GlobalValid はログインのたびに置換/クリーンアップします。Append はシステムルールに追加します。ワークスペースのカスタムマッピングが優先されます。 null 許可: False 選択可能な値: ['ValidOnFirstLogin', 'GlobalValid', 'Append'] 例: ValidOnFirstLogin取得または入力方法: ValidOnFirstLogin、GlobalValid、Append から想定に応じて選択します。既存アカウントの直接ロールの変化を事前に評価してください。 |
パラメータ補足説明¶
認証方式についてはExternal API 署名認証を参照してください。本モジュールはサイトのシステムログインマッピング(isSystem=1)を管理し、OIDC/LDAP など共有ログインマッピング経路を使用するサードパーティログインで使用されます。ワークスペースのカスタムマッピングや独立した SAML 設定 API ではありません。設定の保存によって既存ユーザーすべての権限が直ちに一括再計算されることはなく、後続の関連ログイン時にモードに従って処理されます。
システムマッピングが有効で、対象ワークスペースのカスタムマッピングが無効な場合: ValidOnFirstLogin は、過去に直接のワークスペース関連付けがないアカウントにのみシステムルールを適用します(履歴には削除済みの関連付けも含まれます)。今回新規作成されたアカウントかどうかだけを判定するものではありません。GlobalValid は関連するログインのたびにルールに従って直接ロールを置換し、一致しない場合は直接メンバー/ロール関係を削除することがあります。Append は一致するシステムロールのみを追加し、一致しない場合でも元の直接関係をクリーンアップしません。ワークスペースでカスタムマッピングが有効な場合、そのワークスペースではカスタムルールに従って置換/未一致時のクリーンアップが優先して実行され、システムの Append や初回モードの保持セマンティクスを適用することはできません。システムスイッチを無効にしても、ワークスペースのカスタムルールは同時に無効になりません。既存の直接 Owner ロールはマッチング処理中に保持され、本モジュールを通じて新たに Owner を付与することはありません。
設定はデータベースと Redis キャッシュに段階的に書き込まれます。失敗した場合は、まず読み戻して管理者が永続設定を検証し、モードの切り替えを直接繰り返さないでください。
リクエスト例¶
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/set_disable'
query = {}
data = {'isDisable': False, 'type': 'ValidOnFirstLogin'}
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 です。設定後のオブジェクトは返されません。スイッチ照会 API を呼び出して読み戻してください。 |
{
"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 オブジェクトを送信してください。 |
| 500 | ft.InternalServerError | データベース、サイト設定キャッシュ、監査、または未処理の履歴データの異常 | 内部エラー | traceId を保持し、まずルールまたはスイッチを読み取って現在の状態を確認してください。データベースとキャッシュ/監査は同一トランザクションではないため、エラーが完全に未保存であることを証明するものではありません。 |