Visualizza in anteprima una policy dell'organizzazione

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

Valuta un oggetto di impostazioni candidato senza salvarlo. Il body è lo stesso previsto per creare o sostituire una policy, e il server lo verifica con le stesse regole e con lo stesso controllo del piano, quindi un candidato che PUT rifiuterebbe viene rifiutato qui con lo stesso codice di problema. Non viene scritto nulla: nessuna policy, nessuna voce di audit e nessun evento. La richiesta non accetta If-Match né Idempotency-Key, e la risposta non contiene ETag.

La risposta conta gli utenti a cui si applica il candidato (basis users_in_scope), non gli utenti che verrebbero bloccati, con una sola eccezione: phishing_resistant (vedi sotto). Le condizioni che si conoscono solo al momento dell'accesso, o che il servizio delle policy non possiede, non vengono filtrate; not_evaluated le elenca in modo che il conteggio non venga mai letto come più di quanto sia.

Tipo Utenti conteggiati not_evaluated
authentication_methods Membri attivi dell'organizzazione credentials
mfa (required_for admins o all) Membri attivi dell'organizzazione mfa_enrollment; anche admin_scope per admins
phishing_resistant (required_for admins o all) Membri attivi dell'organizzazione senza una credenziale WebAuthn accettata (basis users_without_webauthn, vedi sotto) credential_policy; anche admin_scope per admins
sso_enforcement org_context Membri attivi dell'organizzazione, meno bypass_user_ids federated_sign_in
sso_enforcement verified_domains Membri attivi, più gli utenti attivi dell'ambiente con un indirizzo email su un dominio verificato di questa organizzazione, meno bypass_user_ids federated_sign_in
session Membri attivi dell'organizzazione nessuno
ip_allowlist Membri attivi dell'organizzazione client_ip; anche admin_scope per admins

Per phishing_resistant, il conteggio e il campione sono gli utenti nell'ambito che oggi non possono accedere in modo resistente al phishing: utenti senza una credenziale WebAuthn attiva (una passkey, oppure una chiave di sicurezza usata come primo fattore) che l'allowlist di AAGUID accetta. L'allowlist è quella del candidato, oppure quella dell'ambiente quando quella del candidato è vuota; con un'allowlist, una credenziale conta solo se il suo modello è elencato e la sua attestazione è stata verificata. Le credenziali in attesa, revocate o sospettate di clonazione non vengono contate. credential_policy significa che il requisito di attestazione dell'ambiente, la regola della passkey legata al dispositivo e lo stato del modello di autenticatore non vengono applicati, quindi il conteggio può essere inferiore al numero di utenti che verrebbero bloccati. Quando l'ambito contiene più di 10.000 utenti, la risposta ricorre a users_in_scope con passkey_enrollment. Se i dati delle credenziali non possono essere letti, la richiesta fallisce con 503 e non viene restituito alcun conteggio.

required_for none e mode off non contano nessuno. Un membro attivo è un membro la cui membership è attiva e il cui utente non è bloccato; ogni utente viene contato una sola volta. admin_scope significa che admins viene contato come tutti i membri, che è il modo in cui l'accesso lo applica oggi. Gli utenti di un'altra organizzazione o di un altro ambiente non vengono mai contati.

Richiesta

Campo Tipo Obbligatorio Descrizione
org_id path sì ID dell'organizzazione (org_…).
policy_kind path sì Tipo di policy: authentication_methods, mfa, phishing_resistant, sso_enforcement, session o ip_allowlist. Qualsiasi altro valore restituisce 404.
settings object sì L'oggetto di impostazioni candidato del tipo, con gli stessi campi previsti per PUT.

Body della richiesta:

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

Risposta

200 OK. sample contiene al massimo 20 utenti dell'insieme conteggiato, ordinati per ID, con solo l'ID utente.

Campo Tipo Descrizione
organization_id string ID dell'organizzazione (org_…).
policy_kind string Il tipo di cui è stata visualizzata l'anteprima.
basis string Ciò che affected_count conta: users_in_scope oppure, per phishing_resistant, users_without_webauthn. Potrebbero essere aggiunti nuovi valori.
affected_count integer Numero di utenti che basis conta.
sample array Al massimo 20 oggetti con user_id (usr_…).
not_evaluated array Condizioni che il conteggio non filtra: admin_scope, credentials, mfa_enrollment, passkey_enrollment, federated_sign_in, client_ip, credential_policy. Potrebbero essere aggiunti nuovi valori. 
{
  "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"
  ]
}

Errori

HTTP code Quando
400 unknown_field Il body contiene un campo che non è nello schema.
403 plan_feature_unavailable Il tipo o l'allowlist di AAGUID richiede un piano superiore; il problema riporta feature e required_plan.
404 not_found L'organizzazione non esiste oppure il tipo è sconosciuto.
409 domain_not_verified sso_enforcement con mode verified_domains richiede un dominio verificato sull'organizzazione.
409 connection_test_required Attivare sso_enforcement (da off oppure da nessuna policy) richiede un test di accesso riuscito della configurazione attuale di almeno uno dei connection_ids nelle ultime 24 ore. Esegui un test di connessione (POST /v1/connections/{connection_id}:test) e riprova.
409 organization_pending_deletion L'organizzazione è in attesa di eliminazione self-service.
422 validation_failed Un campo di impostazioni è sconosciuto o non valido; errors[] punta a /settings/….
422 policy_weaker_than_parent L'impostazione è più debole di quella dell'ambiente; errors[] punta al campo più debole.
422 at_least_one_method authentication_methods non lascia alcun metodo di accesso.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile (per phishing_resistant, anche quando i dati delle credenziali non possono essere letti); riprova dopo il periodo Retry-After.

Esempio

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