マッピングルールの有効化/無効化¶
POST /api/v1/sso_mapping/set_disable
概要¶
単一の SSO 設定に対して、ロールマッピングのスイッチを有効または無効にします。
呼び出し前の準備と使用手順¶
本グループは、特定の SSO プロバイダーのログイン属性を現在のワークスペースのロールにマッピングします。これは、デプロイメントプランの LDAP/OIDC における custom_login_mapping およびシステムマッピングとは異なります。ルールを作成してもマッピングは自動的に有効になりません。対応する SSO 設定で isOpenSAMLMapping(本グループの set_disable)を有効にする必要があり、SSO 設定自体も有効になっている必要があります。
属性名のマッチングは小文字で比較され、値は正規表現/部分一致ではありません。文字列配列は各値ごとにマッチングします。配列ではないオブジェクト/数値/null などは、まず json.dumps で文字列に変換されます。配列要素は一律に文字列へ変換されないため、ID プロバイダーで安定した文字列属性および文字列配列を優先して使用してください。複数のロールにヒットした場合は和集合を取ります。SSO でマッピングを有効にした後、ルールがない/マッチしない場合は、アカウントがこのワークスペースへ入ることを禁止でき、以降のログイン/切り替え時に古い関連付けを削除します。単純にデフォルトロールを追加するわけではありません。書き込み後、ワークスペースとメンバーのキャッシュが非同期で更新されるため、既存の SSO セッションの以降のアクセスに影響する可能性があります。次回ログイン時のみに有効になるとは保証できません。
isDisable=true はマッピングを無効にし、プロバイダーのデフォルトロールロジックに戻ります。以降のログイン時に既存の古いロール関連付けがある場合は保持し、古いロール関連付けがない場合にのみデフォルトロールを補います。既存のマッピング済みロールを一律にデフォルト値へリセットすることはありません。無効化の前に、そのデフォルトロールを検証します。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/sso_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 | 有効化時にワークスペースにアクティブなマッピングが 1 つもない | 有効化失敗、ロールマッピングルールが見つかりません | 対象プロバイダーで実際に使用可能なマッピングを先に作成してから、有効化します。 |
| 400 | ft.InvalidSsoRoleCfg | 無効化時のデフォルトロールが Owner または wsAdmin | 管理者、所有者ロールの設定はサポートされていません | SSO のデフォルトロールを許可値に先に変更します。 |
| 400 | ft.InvalidCustomRole | 無効化時のデフォルトカスタムロールが利用不可/現在のワークスペースで可視のアクティブロールではない | 無効なカスタムロール | 本ワークスペースのロール一覧から使用可能なデフォルトロールを選択します。 |
| 500 | ft.InternalServerError | 保存された JSON 形状、データベース、または送信後のタスクディスパッチで捕捉されない例外が発生 | 内部エラー | データベースはコミット済みでキャッシュタスクのディスパッチが失敗している可能性があります。まず一覧でルール/SSO スイッチを読み戻してから対処し、traceId を保持します。 |