조직 정책 미리 보기

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; admins에 대해서는 admin_scope도 집계
phishing_resistant (required_for admins 또는 all) 승인된 WebAuthn 자격 증명이 없는 조직의 활성 구성원 (basis users_without_webauthn, 아래 참조) credential_policy; admins에 대해서는 admin_scope도 집계
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; admins에 대해서는 admin_scope도 집계

phishing_resistant의 경우 집계 수와 샘플은 범위 내 사용자 중 현재 피싱 저항 방식으로 로그인할 수 없는 사용자입니다. 즉, 활성 WebAuthn 자격 증명이 없는 사용자(패스키, 또는 1차 인증과 함께 사용하는 보안 키)로서 AAGUID 허용 목록이 수락하지 않는 사용자입니다. 허용 목록은 후보의 것이며, 후보가 비어 있으면 환경의 것을 사용합니다. 허용 목록이 있으면 자격 증명은 해당 모델이 목록에 있고 인증(attestation)이 검증된 경우에만 집계됩니다. 대기 중, 취소됨, 복제 의심 자격 증명은 집계되지 않습니다. 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 코드 발생 시점
400 unknown_field 본문에 스키마에 없는 필드가 있습니다.
403 plan_feature_unavailable 해당 종류 또는 AAGUID 허용 목록에 더 높은 플랜이 필요합니다. 문제 응답에는 feature와 required_plan가 포함됩니다.
404 not_found 조직이 없거나 종류를 알 수 없습니다.
409 domain_not_verified mode verified_domains을 사용하는 sso_enforcement에는 조직에 검증된 도메인이 필요합니다.
409 connection_test_required sso_enforcement를 켜려면(off에서 또는 정책이 없는 상태에서) 지난 24시간 동안 connection_ids 중 하나 이상에 대해 현재 구성의 테스트 로그인이 성공해야 합니다. 연결 테스트(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"]}}'