マッピングルールの有効化/無効化(旧互換インターフェース)¶
POST /api/v1/saml/mapping/set_disable
概要¶
単一の SSO 設定に対して、ロールマッピングスイッチを有効または無効にします。
呼び出し前の確認事項と使用手順¶
これは旧アドレス互換インターフェースであり、現在のソースコードでも実際に登録されています。過去の「2026-05-31 廃止」コメントは、現在リクエストが禁止されていることを示すものではありません。新規連携ではマッピングルールの有効化/無効化を優先して使用してください。旧パスは同じコントローラー/リクエストフィールド/レスポンスを踏襲しており、saml プレフィックスのせいで OIDC が除外されることはありません。
本グループは、特定の SSO プロバイダーのログイン属性を現在のワークスペースのロールにマッピングします。これはデプロイメントプランの LDAP/OIDC の custom_login_mapping およびシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping を有効にする必要があり(本グループの set_disable)、SSO 設定自体も有効である必要があります。
属性名の照合は小文字で比較され、値は正規表現/部分一致ではありません。文字列配列は各値ごとに照合されます。配列でないオブジェクト/数値/null などは先に json.dumps で文字列に変換されますが、配列要素は一律に文字列へ変換されません。したがって、ID プロバイダーで安定している文字列属性および文字列配列の使用を優先してください。複数のロールがヒットした場合は和集合を取ります。SSO でマッピングを有効化した後、ルールがない/一致しない場合、アカウントがこのワークスペースへ入ることを禁止でき、以降のログイン/切り替え時に古い関連付けを削除します。単にデフォルトロールを追加するものではありません。書き込み後はワークスペースとメンバーのキャッシュを非同期で更新するため、既存の SSO セッションの以降のアクセスに影響する可能性があり、次回ログイン時のみ有効になるとは保証できません。
isDisable=true でマッピングを無効化し、プロバイダーのデフォルトロールのロジックに戻ります。以降のログインで既存の古いロール関連付けがある場合は保持し、古いロール関連付けがない場合にのみデフォルト role を補完します。既存のマッピング済みロールを一律にデフォルト値へリセットすることはありません。無効化前に、そのデフォルトロールを検証します。general/readOnly またはこのワークスペースで有効なカスタムロールを許可し、Owner/wsAdmin は許可しません。isDisable=false でマッピングを有効化します。現在の実装では、ワークスペースに任意のアクティブなマッピングがあるかどうかのみを確認し、対象の ssoUUID を限定しません。そのため true であっても、そのプロバイダーに一致可能なルールが既にあることを証明できません。まず本グループの list?ssoUUID でルールと対象ロールを確認し、有効化後にアカウントが権限を持たなくなることを避けてください。
この操作は SSOSetting.isOpenSAMLMapping のみを変更し、SSOSetting.status は変更せず、マッピング行を一括無効化しません。SSO 設定自体が無効な場合、マッピングを有効化してもログインは同時に有効になりません。送信後はワークスペース/メンバーのキャッシュを非同期で更新し、SSO 設定変更メールは送信しません。成功しても、すべてのユーザーの認可が正しいことは保証されません。
リクエストヘッダー¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| isDisable | boolean | Y | 必須の真偽値。isOpenSAMLMapping=1/0 を反転制御します。プロバイダー自体の有効/無効ではありません。 null の許可: False 例: false取得または入力方法: false でマッピングを有効化、true で無効化します。 |
| ssoUUID | string | Y | 必須。この操作では、このワークスペース内に削除されていないプロバイダーが存在することを検証します(無効化済みの設定も含む)。 例: sso_example取得または入力方法: このワークスペースの SSO 設定一覧から対象プロバイダーの UUID を取得します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/saml/mapping/set_disable' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"ssoUUID":"sso_example","isDisable":false}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 成功時は true。スイッチの送信およびキャッシュタスクのディスパッチが成功したことのみを示します。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメーター解析に失敗しました | パラメーターの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body がオブジェクトではありません | 一部の json ファイルの形式エラー | ssoUUID/isDisable のオブジェクトを送信してください。 |
| 406 | ft.NotFoundSAML | 対象プロバイダーがこのワークスペースの削除されていない設定に属していません | sso 設定が見つかりません | SSO 一覧から有効な UUID を再取得してください。 |
| 404 | ft.NotFoundSSOMappingEnableFailed | 有効化時にワークスペースにアクティブなマッピングがありません | 有効化に失敗しました。ロールマッピングルールが見つかりません | 先に対象プロバイダーで実際に使用可能なマッピングを作成してから、有効化してください。 |
| 400 | ft.InvalidSsoRoleCfg | 無効化時のデフォルトロールが Owner または wsAdmin | 管理者、オーナーロールの設定はサポートされていません | 先に SSO のデフォルトロールを許可値に変更してください。 |
| 400 | ft.InvalidCustomRole | 無効化時のデフォルトカスタムロールが使用不可/現在のワークスペースで表示されるアクティブなロールではありません | 無効なカスタムロール | このワークスペースのロール一覧から使用可能なデフォルトロールを選択してください。 |
| 500 | ft.InternalServerError | 保存された JSON の形状、データベース、または送信後のタスクディスパッチで未捕捉の例外が発生 | 内部エラー | データベースはコミット済みでキャッシュタスクのディスパッチが失敗した可能性があります。まず一覧でルール/SSO スイッチを読み戻してから対処し、traceId を保持してください。 |