# 組織ポリシーのプレビュー

`POST /v1/organizations/{org_id}/policies/{policy_kind}:preview` · 権限 `organizations:write`

候補となる設定オブジェクトを、保存せずに評価します。リクエストボディは [ポリシーの作成または置き換え](/docs/api/management/organization-policies/put) と同じで、サーバーは同じルールと同じプランの制限で検証します。そのため、`PUT` が拒否する候補は、ここでも同じ問題コードで拒否されます。何も書き込まれません。ポリシー、監査エントリ、イベントのいずれも作成されません。リクエストには `If-Match` も `Idempotency-Key` も指定せず、レスポンスにも `ETag` は含まれません。

レスポンスの件数は、候補が適用されるユーザー数(`basis` `users_in_scope`)です。ブロックされるユーザー数ではありません。例外は `phishing_resistant` です(下記参照)。サインイン時にしか分からない条件や、ポリシーサービスが保持していない条件は除外されません。`not_evaluated` にそれらが一覧されるため、件数を実際より多く読み取ることはありません。

| 種類 | 集計されるユーザー | `not_evaluated` |
|---|---|---|
| `authentication_methods` | 組織のアクティブなメンバー | `credentials` |
| `mfa` (`required_for` `admins` または `all`) | 組織のアクティブなメンバー | `mfa_enrollment`。また `admin_scope` の場合は `admins` も |
| `phishing_resistant` (`required_for` `admins` または `all`) | WebAuthn の承認済み認証情報を持たない、組織のアクティブなメンバー(`basis` `users_without_webauthn`、下記参照) | `credential_policy`。また `admin_scope` の場合は `admins` も |
| `sso_enforcement` `org_context` | 組織のアクティブなメンバーから `bypass_user_ids` を除いたもの | `federated_sign_in` |
| `sso_enforcement` `verified_domains` | アクティブなメンバーに、この組織の検証済みドメイン上のメールアドレスを持つ環境のアクティブなユーザーを加え、`bypass_user_ids` を除いたもの | `federated_sign_in` |
| `session` | 組織のアクティブなメンバー | なし |
| `ip_allowlist` | 組織のアクティブなメンバー | `client_ip`。また `admin_scope` の場合は `admins` も |

`phishing_resistant` の場合、件数とサンプルは、現時点でフィッシング耐性のある方法でサインインできないスコープ内のユーザーです。具体的には、AAGUID 許可リストが受け入れるアクティブな WebAuthn 認証情報(パスキー、または第一要素として使用するセキュリティキー)を持たないユーザーです。許可リストは候補のものを使用し、候補が空の場合は環境のものを使用します。許可リストがある場合、認証情報はそのモデルが記載されており、アテステーションが検証済みの場合にのみ数えられます。保留中、取り消し済み、クローン疑いの認証情報は数えられません。`credential_policy` は、環境のアテステーション要件、デバイスバウンドのパスキーのルール、認証デバイスのモデルステータスが適用されないことを意味します。そのため、ブロックされるユーザー数より件数が少なくなることがあります。スコープのユーザーが 10,000 人を超える場合、レスポンスは `users_in_scope` にフォールバックし、`passkey_enrollment` を返します。認証情報データを読み取れない場合、リクエストは `503` で失敗し、件数は返されません。

`required_for` `none` と `mode` `off` は誰も数えません。アクティブなメンバーとは、メンバーシップが有効で、ユーザーがブロックされていないメンバーです。各ユーザーは一度だけ数えられます。`admin_scope` は、`admins` がすべてのメンバーとして数えられることを意味します。これは、現在サインインでそのように適用されているためです。別の組織や別の環境のユーザーは決して数えられません。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `org_id` | path | はい | 組織 ID(`org_…`)。 |
| `policy_kind` | path | はい | ポリシーの種類: `authentication_methods`、`mfa`、`phishing_resistant`、`sso_enforcement`、`session` または `ip_allowlist`。ほかの値を指定すると `404` が返されます。 |
| `settings` | object | はい | 種類ごとの候補設定オブジェクトです。フィールドは `PUT` と同じです。 |

リクエストボディ:

```json
{
  "settings": {
    "required_for": "all",
    "allowed_factors": [
      "totp",
      "webauthn"
    ],
    "enrollment_grace_days": 7
  }
}
```

## レスポンス

`200 OK`。`sample` には、集計対象のユーザーのうち最大 20 人が ID 順に含まれ、ユーザー ID のみが含まれます。

| フィールド | 型 | 説明 |
|---|---|---|
| `organization_id` | string | 組織 ID(`org_…`)。 |
| `policy_kind` | string | プレビューした種類。 |
| `basis` | string | `affected_count` が数えるもの: `users_in_scope`、または `phishing_resistant` の場合は `users_without_webauthn`。新しい値が追加されることがあります。 |
| `affected_count` | integer | `basis` が数えるユーザー数。 |
| `sample` | array | 最大 20 件のオブジェクト。`user_id`(`usr_…`)を含みます。 |
| `not_evaluated` | array | 件数が絞り込まない条件: `admin_scope`、`credentials`、`mfa_enrollment`、`passkey_enrollment`、`federated_sign_in`、`client_ip`、`credential_policy`。新しい値が追加されることがあります。 |

```json
{
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "policy_kind": "mfa",
  "basis": "users_in_scope",
  "affected_count": 2,
  "sample": [
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4b"
    },
    {
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c"
    }
  ],
  "not_evaluated": [
    "mfa_enrollment"
  ]
}
```

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | 本文にスキーマにないフィールドがあります。 |
| 403 | `plan_feature_unavailable` | 種類または AAGUID 許可リストに、より上位のプランが必要です。問題には `feature` と `required_plan` が含まれます。 |
| 404 | `not_found` | 組織が存在しないか、種類が不明です。 |
| 409 | `domain_not_verified` | `sso_enforcement` を `mode` `verified_domains` とともに使用するには、組織に検証済みドメインが必要です。 |
| 409 | `connection_test_required` | `sso_enforcement` を有効にする(`off` から、または未設定から)には、過去 24 時間以内に、`connection_ids` の少なくとも 1 つで現在の設定によるテストサインインが成功している必要があります。接続テスト(`POST /v1/connections/{connection_id}:test`)を実行してから、再試行してください。 |
| 409 | `organization_pending_deletion` | 組織はセルフサービス削除の待機中です。 |
| 422 | `validation_failed` | 設定フィールドが不明か無効です。`errors[]` は `/settings/…` を示します。 |
| 422 | `policy_weaker_than_parent` | 設定が環境の設定より弱いです。`errors[]` は弱いフィールドを示します。 |
| 422 | `at_least_one_method` | `authentication_methods` によってサインイン方法が残らなくなります。 |
| 401 | `unauthenticated` | 認証情報がない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を置いてから再試行してください。 |
| 503 | `service_unavailable` | 依存サービスが一時的に利用できません(`phishing_resistant` の場合、認証情報データを読み取れないときも含みます)。`Retry-After` の期間を置いてから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/policies/mfa:preview \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'
```

```bash
keenauth organizations policies preview org_01j9xk3m7q8r2s4t6v8w0y2z4a mfa \
  --data '{"settings":{"required_for":"all","allowed_factors":["totp","webauthn"]}}'
```