コンテンツにスキップ

SSO 設定の取得



GET /api/v1/sso/{sso_uuid}/get

概要

単一の SSO 設定、メールアドレス許可リスト、ログイン/コールバック URL を読み取ります。

呼び出し前の確認と使用手順

現在のワークスペースの削除されていない設定のみを読み取ります。無効状態の設定も表示できます。このリクエストは IdP に接続してログインを検証しません。OIDC シークレットの復号は、同じ長さのアスタリスクを生成し、Base64 エンコードして返すためにのみ使用されます。この値を IdP 認証に使用することはできません。get のマスク値と、create/modify が返す保存時の暗号文を混同しないでください。空でない config を変更する際に古いシークレットを保持する場合は、この get の Base64 アスタリスクマスクをそのまま返すことができます。

SAML はアップロードされた XML 全体と SP アドレスを返し、OIDC はログイン URL とコールバック URL を返します。IdP には現在のサイトが返す URL を登録し、独自に URL を組み立てないでください。config フィールドには履歴上の追加データが含まれる場合があります。変更時は、本ページに記載された書き込み契約でサポートされる完全な設定のみを送信し、get レスポンス全体を無条件に Body として送信しないでください。メールアドレス許可リストのレスポンスのキー名は emails で、書き込みリクエストでは emailDomains を使用します。フィールドマッピングはロールマッピングルールとは用途が異なります。

ルートパラメータ

パラメータ名 型 必須 説明
sso_uuid string Y プロバイダー UUID。マッピング UUID、IdP ダイジェスト、クライアント ID ではありません。
例: sso_example
取得または入力方法: SSO 一覧 の content[].uuid から現在のワークスペースの設定を取得します。

リクエストヘッダー

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

パラメータ補足説明

OIDC のカスタムパラメータマッピングはフェーズごとに使用します:

フェーズ サポートされる変数値
authSet $state、$client_id、$client_secret、$redirect_uri、$scope、$response_type(code)、$grant_type;シークレットをブラウザ URL に含めないでください
getTokenSet $state、$code、$client_id、$client_secret、$redirect_uri、$scope、$grant_type;その他のキーがコールバックパラメータ名と一致する場合はその値を取得でき、それ以外は固定テキストとして扱います
getUserInfoSet $client_id、$client_secret、$redirect_uri、$scope、$access_token

マッピングオブジェクトが空でない場合、デフォルトのリクエストパラメータを置き換えます。不足している redirect_uri/code/scope などの必須項目は自動的に補完されません。保存時は一部の URL/client フィールドのみを検証し、完全な認証フローは実行しません。実際のコールバックと最終的なワークスペースアクセスは、専用のテスト用 ID で検証する必要があります。

リクエスト例

curl --get 'https://openapi.guance.com/api/v1/sso/sso_example/get' \
  -H 'DF-API-KEY: <DF-API-KEY>'

レスポンス

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

フィールド 型 説明
content.id integer または null 現在のレコード番号。新規作成を送信する前に構築された結果では null になる場合があります。
content.uuid string sso_ 設定 UUID。
content.type string saml/oidc。
content.workspaceUUID string 所属するワークスペース。
content.idpName string プロバイダーの表示名。
content.remark string または null 備考。旧/新規作成の履歴では null になる場合があります。
content.role string デフォルトロールの識別子。
content.idpMd5 string プロバイダーのアイデンティティ/アカウント名前空間のダイジェスト。クライアントシークレットや書き込み可能な ID ではありません。
content.tokenHoldTime integer 操作がない場合にセッションを保持する秒数。
content.tokenMaxValidDuration integer ログインセッションの最大秒数。
content.isOpenSAMLMapping integer または boolean ロールマッピングのスイッチ(1/0)。SSO 設定の status とは異なります。
content.status integer 0 は有効、2 は無効。削除されていない読み取りでは、他の履歴ステータスを含む場合があります。
content.creator string 作成者のアイデンティティ。
content.updator string 更新者のアイデンティティ。
content.createAt integer 作成日時の Unix 秒。
content.updateAt integer 更新日時の Unix 秒。未更新の場合は -1 になることがあります。
content.deleteAt integer 削除日時の Unix 秒。未削除の場合は -1。
content.uploadData string SAML の元の IdP XML。OIDC では通常、空文字列です。
content.config object 保存された設定。OIDC の clientSecret は get 時に Base64 の全アスタリスクマスクに変換され、平文/保存時の暗号文ではありません。
content.config.modeType string 任意。easy/expert、デフォルトは easy。このフィールドは主に編集モードを保持するもので、任意のエキスパート設定が実行可能であることを自動的に検証するものではありません。
content.config.wellKnowURL string 任意の HTTP(S) ディスカバリー URL。指定した場合、保存フェーズで実際に GET を実行して JSON を解析します(オフライン検証ではありません)。リクエスト失敗/SSL/HTTP エラーは本ページのエラーになります。省略する場合は auth/token/userinfo の 3 つのエンドポイントを明示する必要があり、modeType=expert のみを記述することはできません。
content.config.sslVerify boolean ディスカバリーリクエストの TLS 検証スイッチ。保存フェーズではデフォルト true。実行時 SDK では HTTPS はデフォルト true、HTTP はデフォルト false であり、各エンドポイントの verify を一括制御するスイッチとしては扱われません。
content.config.clientId string OIDC で必須の空でない文字列で、先頭/末尾に空白を含めることはできません。IdP のクライアント登録から取得するもので、Studio API Key ではありません。
content.config.clientSecret string OIDC の Base64 アスタリスクマスク。元のシークレットの長さを表すアスタリスクです。変更時に古いシークレットを保持する場合はそのまま返せますが、デコードして実際のシークレットとして使用することはできません。SAML では通常このフィールドはありません。
content.config.grantType string 任意。authorization_code/code。省略時の実行デフォルトは authorization_code です。client_credentials や password 認可ではありません。
content.config.scope array 任意の文字列配列。実行時 SDK のデフォルトは [openid] のみで、旧説明の openid/profile/email ではありません。IdP がアカウントに必要な email などのクレームを実際に提供することを確認してください。空配列は空の scope を生成するため、クライアントは明示的に適切な設定を行う必要があります。
content.config.scope[] string IdP が許可する単一の scope。本ワークスペースの権限ポイントではありません。
content.config.authSet json 認可リダイレクトのパラメータオブジェクト。省略した場合はディスカバリードキュメントからアドレスが補完されます。
content.config.getTokenSet json code を token に交換するリクエストオブジェクト。省略した場合、エンドポイントはディスカバリードキュメントから取得します。
content.config.verifyTokenSet json id_token の署名検証に使用する JWK オブジェクト。設定保存のために直ちに token 認証を開始するものではありません。
content.config.getUserInfoSet json ユーザー情報のソース/リクエストオブジェクト。デフォルトは origin で、旧説明のデフォルト id_token ではありません。
content.config.claimMapping json アカウントフィールドから IdP の実際の属性名へのマッピングであり、ロールマッピングルールではありません。OIDC の保存では項目ごとの厳密な検証は行われないため、実際にコールバックをテストする必要があります。SAML では空でないマッピングに対して、空でない username/email を同時に指定する必要があり、mobile は任意の文字列です。空オブジェクトは旧デフォルトと互換性があります。
content.config.authSet.url string 任意の明示的な HTTP(S) URL。未指定の場合はディスカバリードキュメントの authorization_endpoint を取得し、値がある場合は実行時のエンドポイントを上書きします。ディスカバリードキュメントがない場合、auth/token/userinfo の 3 つが必須であり、署名検証のソースについては別途 JWK が利用可能であることを確保する必要があります。
content.config.authSet.paramMapping json 任意の非標準リクエストパラメータマッピング。空でない場合、対応するデフォルトパラメータ集合を置き換えるため、必須項目を完全に保持する必要があります。キーは IdP のパラメータ名で、値には本ページで許可される $ 変数または固定文字列を指定できます。clientSecret を認可リダイレクト URL にマッピングしないでください。
content.config.authSet.paramMapping.対象パラメータ名 string 動的な IdP パラメータ値。許可される変数の範囲はフェーズによって異なります(下表参照)。未知の文字列は定数として保持され、任意の内部コンテキストから自動的に取得されることはありません。
content.config.getTokenSet.url string 任意の明示的な HTTP(S) URL。未指定の場合はディスカバリードキュメントの token_endpoint を取得し、値がある場合は実行時のエンドポイントを上書きします。ディスカバリードキュメントがない場合、auth/token/userinfo の 3 つが必須であり、署名検証のソースについては別途 JWK が利用可能であることを確保する必要があります。
content.config.getTokenSet.verify boolean 任意。このエンドポイントでは HTTPS はデフォルト true、HTTP はデフォルト false です。個別に設定するもので、sslVerify によって一律に置き換えられるものではありません。
content.config.getTokenSet.paramMapping json 任意の非標準リクエストパラメータマッピング。空でない場合、対応するデフォルトパラメータ集合を置き換えるため、必須項目を完全に保持する必要があります。キーは IdP のパラメータ名で、値には本ページで許可される $ 変数または固定文字列を指定できます。clientSecret を認可リダイレクト URL にマッピングしないでください。
content.config.getTokenSet.paramMapping.対象パラメータ名 string 動的な IdP パラメータ値。許可される変数の範囲はフェーズによって異なります(下表参照)。未知の文字列は定数として保持され、任意の内部コンテキストから自動的に取得されることはありません。
content.config.verifyTokenSet.url string 任意の明示的な HTTP(S) URL。未指定の場合はディスカバリードキュメントの jwks_uri を取得し、値がある場合は実行時のエンドポイントを上書きします。ディスカバリードキュメントがない場合、auth/token/userinfo の 3 つが必須であり、署名検証のソースについては別途 JWK が利用可能であることを確保する必要があります。
content.config.verifyTokenSet.verify boolean 任意。このエンドポイントでは HTTPS はデフォルト true、HTTP はデフォルト false です。個別に設定するもので、sslVerify によって一律に置き換えられるものではありません。
content.config.getUserInfoSet.url string 任意の明示的な HTTP(S) URL。未指定の場合はディスカバリードキュメントの userinfo_endpoint を取得し、値がある場合は実行時のエンドポイントを上書きします。ディスカバリードキュメントがない場合、auth/token/userinfo の 3 つが必須であり、署名検証のソースについては別途 JWK が利用可能であることを確保する必要があります。
content.config.getUserInfoSet.verify boolean 任意。このエンドポイントでは HTTPS はデフォルト true、HTTP はデフォルト false です。個別に設定するもので、sslVerify によって一律に置き換えられるものではありません。
content.config.getUserInfoSet.paramMapping json 任意の非標準リクエストパラメータマッピング。空でない場合、対応するデフォルトパラメータ集合を置き換えるため、必須項目を完全に保持する必要があります。キーは IdP のパラメータ名で、値には本ページで許可される $ 変数または固定文字列を指定できます。clientSecret を認可リダイレクト URL にマッピングしないでください。
content.config.getUserInfoSet.paramMapping.対象パラメータ名 string 動的な IdP パラメータ値。許可される変数の範囲はフェーズによって異なります(下表参照)。未知の文字列は定数として保持され、任意の内部コンテキストから自動的に取得されることはありません。
content.config.getTokenSet.method string 任意。get/post、デフォルトは post。実行時はこの 2 つのみをサポートします。保存時にこの列挙値は強制されないため、他の値は後続のログイン時にエラーになります。
content.config.getTokenSet.authMethod string 任意。basic/client_secret_basic(デフォルトは Basic ヘッダー)、client_secret_post(デフォルトは ID とシークレットを含むフォーム)、none(デフォルトは client_id のみで、シークレットは自動的に含まれません)。カスタム paramMapping がある場合は完全なマッピングに従ってパラメータを生成しますが、Basic ヘッダーは引き続き選択した認証方式に従います。
content.config.getUserInfoSet.method string デフォルトは get。現在の SDK では get 以外の分岐でも GET を送信しますが、パラメータは Body に配置されるため、実際の POST ではありません。POST を必要とする IdP は、保存成功のみでサポートされていると判断せず、検証済みの GET エンドポイントを使用することを推奨します。
content.config.getUserInfoSet.authMethod string デフォルトは bearer ヘッダー。client_secret_basic は Basic ヘッダーを使用します。none はデフォルトで access_token をパラメータに配置します。basic の別名やその他の任意の値を同じように有効とはみなしません。
content.config.getUserInfoSet.source string origin は userinfo を呼び出します(デフォルト)。id_token は id_token を検証して読み取ります。merge は先に id_token、次に userinfo で同名キーを上書きします。保存時に列挙値は強制されないため、他の値では最終的にユーザー情報が得られない可能性があります。
content.config.getUserInfoSet.responseInfoPath string 任意。レスポンス内のユーザーオブジェクトのドットパスで、origin の結果からのみ抽出します。空文字列の場合はレスポンス全体を取得します。claimMapping の属性名とは異なります。
content.config.verifyTokenSet.keys array 任意の IdP 公開 JWK 配列。空でない場合は署名検証に直接使用し、そうでない場合は実行時に verifyTokenSet.url を GET して keys を取得します。秘密鍵ではなく、例のプレースホルダー素材を実際の署名検証設定として扱わないでください。
content.config.verifyTokenSet.keys[] json 単一の公開 JWK。IdP が公開する kty/alg/kid および公開鍵パラメータに従って完全な構造を保持します。
content.config.verifyTokenSet.keys[].kty string 公開鍵の種類(例: RSA/EC)。IdP の JWK に従います。
content.config.verifyTokenSet.keys[].kid string 公開鍵の選択に使用する識別子。
content.config.verifyTokenSet.keys[].use string 鍵の用途。
content.config.verifyTokenSet.keys[].alg string 署名検証アルゴリズムの識別子。
content.config.verifyTokenSet.keys[].n string RSA モジュラスの Base64url。
content.config.verifyTokenSet.keys[].e string RSA 公開指数の Base64url。
content.config.verifyTokenSet.keys[].crv string EC 曲線。該当する種類のみ。
content.config.verifyTokenSet.keys[].x string EC 公開 x 座標。
content.config.verifyTokenSet.keys[].y string EC 公開 y 座標。
content.config.verifyTokenSet.keys[].x5c array 公開証明書チェーンの Base64 DER 配列。任意。
content.config.verifyTokenSet.keys[].x5c[] string 単一の公開証明書。秘密鍵は含みません。
content.config.verifyTokenSet.keys[].その他の公開フィールド JSON IdP JWK の拡張はライブラリのプロトコルに従って保持し、d/p/q などの秘密鍵素材を追加しません。
content.config.claimMapping.username string OIDC のデフォルトは preferred_username、SAML のデフォルトは username。SAML で空でない claimMapping を明示する場合、空でない文字列が必須です。
content.config.claimMapping.email string デフォルトは email。実際のログインでは有効なメールアドレスを取得する必要があります。SAML で空でない claimMapping を明示する場合は必須です。OIDC の保存では値/ソースは検証されませんが、コールバックでは引き続きメールアドレスが必要です。
content.config.claimMapping.name string OIDC の任意の表示名属性。デフォルトは name。SAML は現在 name を固定で読み取り、このマッピングキーは表示名の抽出方法を変更しません。
content.config.claimMapping.mobile string OIDC のデフォルトは phone_number、SAML のデフォルトは mobile で、明示的な空文字列は抽出されません。番号がない場合は補完されず、既存の携帯電話番号と市外局番は保持されます。元のアカウントに番号がなく、IdP の番号が有効な場合にのみ補完されます。
content.config.authSet.verify boolean 既存データとの互換性のために保存できますが、現在の OIDC SDK はこのキーを使用しないため、これに基づいてリクエスト/TLS を制御することはできません。本ページで実際に読み取られる対応フィールドを使用してください。
content.config.verifyTokenSet.method string 既存データとの互換性のために保存できますが、現在の OIDC SDK はこのキーを使用しないため、これに基づいてリクエスト/TLS を制御することはできません。本ページで実際に読み取られる対応フィールドを使用してください。
content.config.verifyTokenSet.authMethod string 既存データとの互換性のために保存できますが、現在の OIDC SDK はこのキーを使用しないため、これに基づいてリクエスト/TLS を制御することはできません。本ページで実際に読み取られる対応フィールドを使用してください。
content.emails array<string> 現在の削除されていないメールアドレス/ドメイン許可リストの値。許可リストのエンティティは返しません。
content.emails[] string 単一の完全なメールアドレスまたはドメイン識別子。
content.loginURL string このプロバイダーのログインエントリーポイント。デプロイサイトによって返され、DF-API-KEY を使用してアクセスする現在の OpenAPI パスではありません。
content.callbackURL string OIDC 専用のコールバック URL。IdP の許可されたコールバックリストに登録する必要があります。
content.metadataURL string SAML 専用の SP メタデータアドレス。
content.entiryID string SAML 専用の SP エンティティ ID。プロトコル上の実際の綴り entiryID を保持し、entityID に変更しないでください。
content.assertionURL string SAML 専用の ACS/アサーションコールバックアドレス。実際に返された内容に従って登録します。
content.declaration object 空でないオブジェクトの公開宣言。
{
  "code": 200,
  "content": {
    "id": 1,
    "uuid": "sso_example",
    "type": "oidc",
    "workspaceUUID": "wksp_example",
    "idpName": "ExampleIdP",
    "remark": "企業ログイン",
    "role": "general",
    "idpMd5": "IDP-IDENTITY-HASH",
    "tokenHoldTime": 604800,
    "tokenMaxValidDuration": 2592000,
    "isOpenSAMLMapping": 0,
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427200,
    "deleteAt": -1,
    "uploadData": "",
    "config": {
      "modeType": "expert",
      "clientId": "client_example",
      "clientSecret": "KioqKioqKioq",
      "scope": [
        "openid",
        "profile",
        "email"
      ],
      "grantType": "authorization_code",
      "authSet": {
        "url": "https://idp.example.com/authorize"
      },
      "getTokenSet": {
        "url": "https://idp.example.com/token",
        "method": "post",
        "authMethod": "client_secret_basic"
      },
      "verifyTokenSet": {
        "url": "https://idp.example.com/jwks"
      },
      "getUserInfoSet": {
        "url": "https://idp.example.com/userinfo",
        "method": "get",
        "authMethod": "bearer",
        "source": "origin"
      },
      "claimMapping": {
        "username": "preferred_username",
        "email": "email",
        "mobile": "phone_number"
      }
    },
    "emails": [
      "example.com"
    ],
    "loginURL": "https://sso.example.com/oidc/login/sso_example",
    "callbackURL": "https://sso.example.com/oidc/callback/sso_example",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

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

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対処方法
406 ft.NotFoundSAML UUID が現在のワークスペースの削除されていない SSO 設定に属していない sso 設定が見つかりません SSO 一覧 から sso_ UUID を再取得し、fdmp_ マッピングや idpMd5 を使用しないでください。
500 ft.InternalServerError 設定/データベース/鍵の復号、XML ツール、または関連資料のフォーマットで未捕捉の例外が発生 内部エラー traceId を保持し、現在の設定とサービス依存関係を確認してください。読み取りは設定更新を実行しないため、その失敗をプロバイダーが存在しないこととして扱わないでください。

フィードバック

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