Kuruluş politikasını önizleyin

POST /v1/organizations/{org_id}/policies/{policy_kind}:preview · İzin organizations:write

Aday bir ayarlar nesnesini kaydetmeden değerlendirir. Gövde, politika oluşturma veya değiştirme ile aynıdır; sunucu bunu aynı kurallarla ve aynı plan kapısıyla denetler. Bu nedenle PUT reddedecek bir aday, burada aynı sorun koduyla reddedilir. Hiçbir şey yazılmaz: politika, denetim kaydı ve olay oluşturulmaz. İstek If-Match ve Idempotency-Key almaz, yanıt ise ETag içermez.

Yanıt, engellenecek kullanıcıları değil, adayın uygulandığı kullanıcıları sayar (basis users_in_scope); bir istisna dışında: phishing_resistant (aşağıya bakın). Yalnızca oturum açma sırasında bilinen veya politika hizmetinin tutmadığı koşullar filtrelenmez; not_evaluated bunları listeler, böylece sayı olduğundan fazla gibi okunmaz.

Tür Sayılan kullanıcılar not_evaluated
authentication_methods Kuruluşun etkin üyeleri credentials
mfa (required_for admins veya all) Kuruluşun etkin üyeleri mfa_enrollment; ayrıca admin_scope için admins
phishing_resistant (required_for admins veya all) Kabul edilmiş bir WebAuthn kimlik bilgisi olmayan kuruluşun etkin üyeleri (basis users_without_webauthn, aşağıya bakın) credential_policy; ayrıca admin_scope için admins
sso_enforcement org_context Kuruluşun etkin üyeleri, eksi bypass_user_ids federated_sign_in
sso_enforcement verified_domains Etkin üyeler, artı bu kuruluşun doğrulanmış bir alan adındaki e-posta adresine sahip ortamın etkin kullanıcıları, eksi bypass_user_ids federated_sign_in
session Kuruluşun etkin üyeleri yok
ip_allowlist Kuruluşun etkin üyeleri client_ip; ayrıca admin_scope için admins

phishing_resistant için sayı ve örnek, bugün phishing'e dayanıklı biçimde oturum açamayan kapsamdaki kullanıcılardır: AAGUID izin listesinin kabul ettiği, etkin bir WebAuthn kimlik bilgisi (bir passkey veya birinci faktörle kullanılan bir güvenlik anahtarı) olmayan kullanıcılar. İzin listesi adayınkidir; adayınki boşsa ortamınkidir. Bir izin listesi varsa, bir kimlik bilgisi yalnızca modeli listelenmişse ve onayı doğrulanmışsa sayılır. Beklemedeki, iptal edilmiş ve klonlanmış şüphesi olan kimlik bilgileri sayılmaz. credential_policy, ortamın onaylama gereksiniminin, cihaza bağlı passkey kuralının ve kimlik doğrulayıcı model durumunun uygulanmadığı anlamına gelir; bu nedenle sayı, engellenecek kullanıcı sayısından düşük olabilir. Kapsamda 10.000'den fazla kullanıcı olduğunda yanıt users_in_scope moduna geçer ve passkey_enrollment döner. Kimlik bilgisi verileri okunamazsa istek 503 ile başarısız olur ve sayı döndürülmez.

required_for none ve mode off hiçbir kullanıcıyı saymaz. Etkin üye, üyeliği etkin ve kullanıcısı engellenmemiş olan üyedir; her kullanıcı bir kez sayılır. admin_scope, admins değerinin tüm üyeler olarak sayıldığı anlamına gelir; oturum açma bugün bunu böyle uygular. Başka bir kuruluşun veya başka bir ortamın kullanıcıları hiçbir zaman sayılmaz.

İstek

Alan Tür Zorunlu Açıklama
org_id yol evet Kuruluş kimliği (org_…).
policy_kind yol evet Politika türü: authentication_methods, mfa, phishing_resistant, sso_enforcement, session veya ip_allowlist. Başka bir değer 404 döndürür.
settings nesne evet Türün aday ayarlar nesnesi; PUT ile aynı alanlara sahiptir.

İstek gövdesi:

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

Yanıt

200 OK. sample, sayılan kümedeki en fazla 20 kullanıcıyı, yalnızca kullanıcı kimliğiyle ve kimliğe göre sıralı olarak içerir.

Alan Tür Açıklama
organization_id string Kuruluş kimliği (org_…).
policy_kind string Önizlenen tür.
basis string affected_count neyi sayar: users_in_scope veya phishing_resistant için users_without_webauthn. Yeni değerler eklenebilir.
affected_count integer basis tarafından sayılan kullanıcı sayısı.
sample array user_id alanlı en fazla 20 nesne (usr_…).
not_evaluated array Sayının filtrelemediği koşullar: admin_scope, credentials, mfa_enrollment, passkey_enrollment, federated_sign_in, client_ip, credential_policy. Yeni değerler eklenebilir. 
{
  "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"
  ]
}

Hatalar

HTTP code Ne zaman
400 unknown_field Gövdede şemada olmayan bir alan var.
403 plan_feature_unavailable Tür veya AAGUID izin listesi daha yüksek bir plan gerektirir; sorun feature ve required_plan bilgilerini içerir.
404 not_found Kuruluş yok veya tür bilinmiyor.
409 domain_not_verified sso_enforcement ile mode verified_domains kuruluşta doğrulanmış bir alan adı gerektirir.
409 connection_test_required sso_enforcement etkinleştirmek (off veya hiç politika olmadan), connection_ids arasından en az birinin son 24 saat içindeki geçerli yapılandırmasıyla başarılı bir test oturum açması gerektirir. Bir bağlantı testi (POST /v1/connections/{connection_id}:test) çalıştırın ve yeniden deneyin.
409 organization_pending_deletion Kuruluş, self-servis silme işlemini bekliyor.
422 validation_failed Bir ayar alanı bilinmiyor veya geçersiz; errors[], /settings/… öğesini gösterir.
422 policy_weaker_than_parent Ayar, ortamın ayarından daha zayıf; errors[] zayıf alanı gösterir.
422 at_least_one_method authentication_methods hiçbir oturum açma yöntemi bırakmıyor.
401 unauthenticated Kimlik bilgisi eksik, geçersiz veya iptal edilmiş.
403 insufficient_permissions Kimlik bilgisi gerekli izne sahip değil.
429 rate_limited Hız sınırı aşıldı; Retry-After süresinden sonra yeniden deneyin.
503 service_unavailable Bir bağımlılık geçici olarak kullanılamıyor (phishing_resistant için, kimlik bilgisi verileri okunamadığında da); Retry-After süresinden sonra yeniden deneyin.

Örnek

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