コンテンツにスキップ

マッピングルール一覧の取得(旧互換インターフェース)



GET /api/v1/saml/mapping/field/list

概要

プロバイダーとキーワードでページングして SSO ロールマッピングルールを取得します。

呼び出し前の準備と使用手順

これは旧アドレスの互換インターフェースであり、現在のソースコードでも実際に登録されています。過去の「2026-05-31 廃止」というコメントは、現在リクエストが禁止されていることを示すものではありません。新規の接続では マッピングルール一覧の取得 を優先して使用してください。旧パスは同じコントローラー/リクエストフィールド/レスポンスを踏襲しており、saml プレフィックスのために OIDC が除外されることはありません。

本グループは、特定の SSO プロバイダーのログイン attributes を現在のワークスペースのロールにマッピングします。これはデプロイメントプランの LDAP/OIDC の custom_login_mapping およびシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping を有効化する必要があり(本グループの set_disable)、SSO 設定自体も有効になっている必要があります。

属性名のマッチングは小文字で比較され、値は正規表現/部分一致ではありません。文字列配列は各値ごとにマッチングします。配列でないオブジェクト/数値/null などはまず json.dumps で文字列に変換されますが、配列要素は一律には文字列に変換されません。そのため、アイデンティティソースで安定した文字列属性および文字列配列を使用することを推奨します。複数のロールがヒットした場合は和集合を取ります。SSO でマッピングを有効にした後、ルールがない/マッチしない場合はアカウントのこのワークスペースへの進入を禁止でき、その後のログイン/切り替え時に古い関連付けが削除されます。既定のロールを単純に追加するものではありません。書き込み後はワークスペースとメンバーのキャッシュが非同期に更新されるため、既存の SSO セッションの以降のアクセスに影響する可能性があります。次回ログイン時のみ有効になるとは保証できません。

現在のワークスペースの未削除ルールのみを対象とし、既定では updateAt の降順で並びます。異なるプロバイダーをまとめて一覧表示できます。search はソースフィールド、ソース値、ロール名の間で OR、ssoUUID のフィルターとは AND で結合されます。ssoInfo={} は、本ワークスペースに未削除のプロバイダーが見つからなかったことを示しますが、本インターフェースは当該マッピングを自動で削除/修復しません。返されるのは設定であり、あるアカウントで現在実際に有効なロールではありません。

リクエストヘッダー

パラメーター名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得/入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Query リクエストパラメーター

パラメーター名 型 必須 説明
pageIndex integer 任意、既定 1、>=1。
null 許可: False
$minValue: 1
例: 1
取得/入力方法: 1 ページ目は 1、pageInfo に従ってページを移動します。
pageSize integer 任意、既定 10。
null 許可: False
$maxValue: 100
$minValue: 1
例: 10
取得/入力方法: 必要に応じて 1..100 件を選択します。
search string 任意、trim 後に曖昧一致、SQL のワイルドカード文字が LIKE に影響する可能性があります。
null 許可: False
例: engineering
取得/入力方法: 属性名/値またはロール表示名のキーワードを指定します。
ssoUUID string 任意、≤48 文字。trim 後に空値の場合はフィルターせず、非空の場合は完全一致で絞り込みます。プロバイダーの存在は検証されません。
null 許可: False
最大長: 48
例: sso_example
取得/入力方法: 本ワークスペースの SSO 一覧からプロバイダー UUID を取得します。

リクエスト例

curl --get 'https://openapi.guance.com/api/v1/saml/mapping/field/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode ssoUUID=sso_example \
  --data-urlencode pageIndex=1 \
  --data-urlencode pageSize=10

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。

フィールド 型 説明
content.data array<object> 本ページのマッピング配列。
content.data[].id integer データベースレコード番号。
content.data[].uuid string fdmp_マッピング UUID。変更/削除に使用します。
content.data[].workspaceUUID string 現在のワークスペース。
content.data[].ssoUUID string 保存されたプロバイダー UUID。現在も存在するか、現在のワークスペースに属しているかは保証されません。
content.data[].sourceField string 属性フィールド名。
content.data[].sourceValue string マッチング対象のフィールド値。
content.data[].targetValues array<string> 保存されたロール識別子の配列。無効な履歴値が含まれる可能性があります。
content.data[].targetValues[] string 単一のロール識別子。
content.data[].roleInfos array<object> 本ワークスペースで参照可能かつ status=0 のロール概要。無効なロールは省略されます。
content.data[].roleInfos[].uuid string ロール UUID。
content.data[].roleInfos[].name string ロール名。
content.data[].ssoInfo object 本ワークスペースの未削除プロバイダーの概要。有効な一致がない場合は {}。
content.data[].ssoInfo.uuid string プロバイダー UUID。省略可能。
content.data[].ssoInfo.idpName string プロバイダー名。省略可能。
content.data[].status integer 未削除レコードのステータス。通常は 0、履歴では 2 の場合があります。
content.data[].creator string 作成者の識別情報。
content.data[].updator string 更新者の識別情報。
content.data[].createAt integer 作成時刻(Unix 秒)。
content.data[].updateAt integer 更新時刻(Unix 秒)。未更新の場合は -1 の可能性があります。
content.data[].deleteAt integer 削除時刻(Unix 秒)。未削除の場合は -1。
content.declaration object 外側の共通宣言。data の各項目には再帰的に追加されません。
pageInfo.pageIndex integer 現在のページ。
pageInfo.pageSize integer ページサイズ。
pageInfo.count integer 本ページの件数。
pageInfo.totalCount integer フィルターに一致した総件数。
{
  "code": 200,
  "content": {
    "data": [
      {
        "id": 1,
        "uuid": "fdmp_example",
        "workspaceUUID": "wksp_example",
        "ssoUUID": "sso_example",
        "sourceField": "groups",
        "sourceValue": "engineering",
        "targetValues": [
          "general"
        ],
        "roleInfos": [
          {
            "uuid": "general",
            "name": "标准成员"
          }
        ],
        "ssoInfo": {
          "uuid": "sso_example",
          "idpName": "ExampleIdP"
        },
        "status": 0,
        "creator": "wsak_example",
        "updator": "wsak_example",
        "createAt": 1785427200,
        "updateAt": 1785427200,
        "deleteAt": -1
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE",
  "pageInfo": {
    "pageIndex": 1,
    "pageSize": 10,
    "count": 1,
    "totalCount": 1
  }
}

エラーレスポンス

認証、レート制限、共通リクエストエラーについては 共通エラー定義 を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対応方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメーターの解析に失敗しました パラメーターの位置、フィールド名、型、値を確認してください。
500 ft.InternalServerError 読み取った履歴 JSON の形状、データベース、またはロール/プロバイダー情報のフォーマット処理で例外が発生した 内部エラー 特定のプロバイダー/ルールに絞り込み、履歴 targetValues の形状を確認してください。継続的に失敗する場合は traceId を保持してください。

フィードバック

このページは役に立ちましたか?