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

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

候補となる設定オブジェクトを、保存せずに評価します。リクエストボディは ポリシーの作成または置き換え と同じで、サーバーは同じルールと同じプランの制限で検証します。そのため、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 と同じです。

リクエストボディ:

{
  "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。新しい値が追加されることがあります。 
{
  "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 の期間を置いてから再試行してください。

例

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"]}}'

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