SSO 設定の取得(旧互換インターフェース)¶
GET /api/v1/sso/saml_get/{sso_uuid}
概要¶
単一の SSO 設定、メールアドレス許可リスト、ログイン/コールバックアドレスを読み取ります。
呼び出し前と使用手順¶
これは旧アドレス互換インターフェースであり、現在のソースコードでも実際に登録されています。過去の「2026-05-31 提供終了」というコメントは、現在リクエストが禁止されていることを示すものではありません。新規接続ではSSO 設定の取得を優先して使用してください。旧パスは同じコントローラー、リクエストフィールド、レスポンスを使用しており、saml プレフィックスのために OIDC が除外されることはありません。
現在のワークスペース内の削除されていない設定のみを読み取り、無効状態でも表示できます。このリクエストは IdP に接続してログインを検証しません。OIDC secret の復号は、同じ長さのアスタリスクを生成し、Base64 エンコードして返すためにのみ使用されます。この値を使用して IdP に対して認証することはできません。get のマスク値を create/modify が返す保存暗号文と混同しないでください。空でない config を変更する際に古い secret を保持する場合は、この 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;secret をブラウザーの 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 フィールドのみを検証し、完全な認証フローは実行しません。実際のコールバックと最終的なワークスペースアクセスは、専用のテストアイデンティティで確認する必要があります。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/sso/saml_get/sso_example' \
-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) ディスカバリーアドレス。指定した場合、保存段階で実際に 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 アスタリスクマスクで、元の secret の長さを表すアスタリスクです。変更時に古い secret を保持する場合はそのまま返すことができ、デコードして実際の secret として使用することはできません。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 と secret を含むフォーム)、none(デフォルトは client_id のみで、secret を自動的に含めません)。カスタム 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 を保持し、現在の設定とサービス依存関係を確認してください。読み取りでは設定更新を実行しないため、この失敗をプロバイダーが存在しないこととして扱わないでください。 |