API Single sign-on

Indica alla pagina di accesso come un indirizzo email accede o si registra. sso, required e provider_name dipendono solo dal dominio dell’indirizzo, rispetto ai domini verificati delle organizzazioni che hanno una connessione con un provider di identità attiva: sso è true quando una tale organizzazione possiede il dominio. required è true quando quell’organizzazione richiede il single sign-on, che rifiuta l’accesso con password e passkey per il dominio (createDashboardSession risponde sso_required); i suoi amministratori di emergenza mantengono l’accesso con passkey. provider_name è il nome visualizzato della connessione, presente solo quando sso è true. account è true quando una persona attiva possiede l’indirizzo, verificato o meno, e false quando nessuno lo possiede: la pagina fa accedere la persona quando è true e propone la registrazione (POST /api/signups) quando è false e sso è false.

Limitato per indirizzo client.

Avvia un accesso single sign-on tramite il provider di identità dell’organizzazione che possiede il dominio dell’indirizzo e risponde con l’indirizzo del provider, a cui la pagina naviga. La risposta imposta il cookie __Host-screenrig-sso (HttpOnly, Secure, SameSite=Strict, Path=/, 10 minuti) che lega questo browser all’accesso.

A una connessione OIDC viene richiesto il flusso authorization code con PKCE S256, un nonce e response_mode form_post; una connessione SAML riceve un AuthnRequest HTTP-Redirect.

Il provider risponde inviando con POST all’indirizzo della connessione, /api/sso/oidc/{connection_id}/callback o /api/sso/saml/{connection_id}/acs, e l’accesso termina su /api/sso/finish. return_to è un percorso sotto /dashboard/ su cui termina l’accesso; se assente termina su /dashboard/. invitation_token è un invito che l’accesso accetta una volta che la persona ha effettuato l’accesso. prompt none chiede al provider un accesso silenzioso, che termina su /dashboard/#sso_error=interaction_required quando la persona deve intervenire; prompt login fa autenticare di nuovo la persona dal provider.

Un indirizzo il cui dominio non ha alcuna connessione abilitata è not_found. Limitato per indirizzo client.

Il redirect URI OIDC di una connessione. Il provider di identità invia qui i dati con POST da un altro sito (response_mode form_post), quindi non arriva alcun cookie del dashboard. La rotta non fa accedere nessuno: risponde con una pagina che invia con POST gli stessi membri e l’id della connessione a /api/sso/finish dall’origine del dashboard, dove arriva il cookie di transazione.

Una risposta conclude solo un accesso avviato da questa connessione; qualsiasi altra termina su /dashboard/#sso_error=bad_state. Quando il documento di discovery del provider imposta authorization_response_iss_parameter_supported, una risposta senza iss (RFC 9207) termina su /dashboard/#sso_error=verification_failed.

La pagina esegue un solo script inline protetto da un nonce e contiene un pulsante noscript; la sua Content-Security-Policy è restrittiva, Cache-Control è no-store e Referrer-Policy è no-referrer. Un id che nessuna connessione possiede è not_found.

I metadati del service provider SAML di una connessione. Il suo entityID è l’indirizzo di questa rotta e il suo assertion consumer service è /api/sso/saml/{connection_id}/acs con il binding HTTP-POST. Un amministratore del provider di identità li importa, oppure copia gli stessi valori da service_provider della connessione. Un id che nessuna connessione possiede è not_found.

L’assertion consumer service SAML di una connessione. Il provider di identità invia qui i dati con POST da un altro sito, quindi non arriva alcun cookie del dashboard. La rotta non fa accedere nessuno: risponde con una pagina che invia con POST la SAMLResponse, il relativo RelayState e l’id della connessione a /api/sso/finish dall’origine del dashboard, dove arriva il cookie di transazione.

Una risposta conclude solo un accesso avviato da questa connessione. La pagina esegue un solo script inline protetto da un nonce e contiene un pulsante noscript; la sua Content-Security-Policy è restrittiva, Cache-Control è no-store e Referrer-Policy è no-referrer. Un id che nessuna connessione possiede è not_found.

Conclude un accesso single sign-on sull’origine del dashboard, dove arriva il cookie __Host-screenrig-sso. Il modulo contiene state, la connessione per cui è arrivata la risposta e la risposta del provider di identità così come l’ha copiata la pagina di callback: code, error, error_description e iss per OIDC, SAMLResponse per SAML (state è il RelayState).

La rotta lega state al cookie, rifiuta una risposta arrivata per una connessione diversa da quella con cui è stato avviato l’accesso, verifica il token o l’assertion del provider, applica le regole di adozione e collegamento dell’account, controlla la politica di accesso dell’organizzazione e risponde 303.

Un accesso, un rinnovo o una riautenticazione emette una sessione dashboard con auth_method sso, che dura 24 ore da questo accesso e non viene prolungata dall’uso, accetta l’invito che l’accesso porta con sé, imposta il cookie __Host-screenrig-dashboard, fa scadere il cookie di transazione e reindirizza a return_to, oppure a /dashboard/.

Un link aggiunge l’identità all’account della persona connessa e ne mantiene la sessione. Un test registra il proprio esito sulla connessione (last_test) e non fa accedere nessuno. Anche ogni errore risponde con 303, a /dashboard/#sso_error=<code>, e mai con un documento problem.

I codici sono no_email, email_unverified, domain_not_allowed, account_exists (la persona accede come prima e collega l’identità dal proprio account), managed_elsewhere, subject_mismatch, not_provisioned, sso_required, staff_account, expired, bad_state, interaction_required (un rinnovo silenzioso richiede la persona), provider_refused, provider_unavailable, verification_failed e deactivated (SSOErrorCode).

Avvia un accesso single sign-on per la persona connessa e risponde con l’indirizzo del provider di identità, come fa POST /api/sso/starts per un indirizzo, impostando il cookie __Host-screenrig-sso. intent renew rinnova in modo silenzioso (prompt none) una sessione che ha effettuato l’accesso tramite single sign-on, prima che le sue 24 ore terminino; il dashboard lo fa una volta trascorse 12 ore. intent reauth fa autenticare di nuovo la persona dal provider (prompt login), il che dà alla sessione l’accesso recente di cui ha bisogno la prova sso. intent link collega l’identità della persona presso il provider al suo account esistente. renew e reauth richiedono una sessione che ha effettuato l’accesso tramite single sign-on, e link richiede una connessione abilitata sul dominio verificato della persona; altrimenti la risposta è resource_conflict. return_to è un percorso sotto /dashboard/.

Un amministratore designato legge la connessione single sign-on dell’organizzazione: il suo protocollo e provider, i valori del service provider da inserire nel provider di identità (il redirect URI OIDC, l’entity ID SAML, gli indirizzi dell’assertion consumer service e dei metadati), la sua politica di accesso e l’esito dell’ultimo test.

Il client secret non viene mai restituito; client_secret_set indica se ne è memorizzato uno. ready_to_require è true quando l’organizzazione possiede un dominio verificato e un test o un accesso reale è riuscito tramite l’identità attuale della connessione (il suo issuer, tenant, entity ID e kind); Require SSO è accettato solo finché è true. L’ETag contiene la revisione.

Un’organizzazione senza connessione è not_found. Chiunque altro è rifiutato come nelle altre rotte admin dell’organizzazione. Solo persone; agenti e credenziali bearer non hanno alcuna rotta.

Un amministratore designato crea la connessione dell’organizzazione o la modifica; un’organizzazione ne ha una sola.

If-Match contiene la revisione della connessione ottenuta da GET, oppure 0 quando l’organizzazione non ne ha una, ed è obbligatorio; un valore obsoleto è revision_conflict con current_revision. 201 crea e 200 modifica. proof è obbligatorio: una prova recente con passkey o password legata a una riautenticazione di tipo identity_provider_change con l’id dell’organizzazione come subject_id, oppure {type: sso} da una sessione che ha effettuato l’accesso tramite single sign-on al massimo 10 minuti fa (altrimenti reauthentication_required).

OIDC con preset entra accetta tenant_id e ne ricava l’issuer; il preset generic accetta issuer. Omettere oidc.client_secret mantiene il segreto memorizzato.

Per SAML, metadata_xml viene letto per l’entity ID, l’indirizzo di accesso e i certificati di firma del provider di identità, mentre idp_entity_id, idp_sso_url e certificates_pem li indicano direttamente; certificates_pem sostituisce l’elenco memorizzato, che contiene al massimo 4 certificati, così un nuovo certificato può sovrapporsi al vecchio durante la rotazione.

Finché Require SSO è in vigore, una modifica dell’identità (issuer, tenant, entity ID o kind) è resource_conflict e la rotazione di certificati e client secret è consentita; al di fuori di esso, una modifica dell’identità rende ready_to_require false finché un test o un accesso non riesce. Restituisce la connessione con il suo ETag. Solo persone; agenti e credenziali bearer non hanno alcuna rotta.

Creare la prima connessione (If-Match 0) rientra nel single sign-on, che il piano Enterprise include; un’organizzazione il cui piano ne è privo viene rifiutata con feature_not_in_plan (402).

Modificare una connessione esistente, ad esempio ruotare un certificato o un client secret o aggiornare i metadati, leggerla, testarla e rimuoverla sono operazioni disponibili in ogni piano, e una connessione esistente continua a far accedere le persone.

Un amministratore designato rimuove la connessione dell’organizzazione dopo una prova recente (il corpo contiene proof, come per PUT). Risponde resource_conflict mentre Require SSO è in vigore, rimozione pianificata inclusa, e not_found quando l’organizzazione non ha alcuna connessione. Solo persone; agenti e credenziali bearer non hanno alcuna rotta.

Un amministratore designato avvia un accesso di prova tramite la connessione dell’organizzazione, per verificarne il funzionamento prima di renderla obbligatoria. Risponde con l’indirizzo del provider di identità a cui la pagina deve navigare e imposta il cookie __Host-screenrig-sso.

La risposta del provider termina su /api/sso/finish, che registra l’esito sulla connessione (last_test; un successo permette a ready_to_require di diventare true) e riporta il browser al dashboard. Un test non fa accedere nessuno. Un’organizzazione senza connessione è not_found. Solo persone; agenti e credenziali bearer non hanno alcuna rotta.

Un amministratore designato attiva o disattiva Require SSO e indica gli amministratori break-glass. required true rifiuta l’accesso con password e passkey per i domini verificati dell’organizzazione (sso_required) e richiede un dominio verificato e ready_to_require sulla connessione, altrimenti resource_conflict; incrementa policy_revision. required false non revoca subito l’obbligo: pianifica la rimozione 72 ore dopo la richiesta (enforcement_ends_at) e invia un’email a ogni amministratore, e DELETE .../sso-policy/removal la annulla. break_glass_user_ids indica al massimo 2 amministratori designati che hanno una passkey, altrimenti invalid_request; mantengono l’accesso con passkey mentre SSO è obbligatorio, e ogni accesso di questo tipo è registrato nell’audit.

If-Match contiene policy_revision ed è obbligatorio; un valore obsoleto è revision_conflict con current_revision. proof è obbligatorio: una prova recente con passkey o password legata a una riautenticazione di tipo sso_policy_change con l’id dell’organizzazione come subject_id, oppure {type: sso} da una sessione che ha effettuato l’accesso tramite single sign-on al massimo 10 minuti fa.

Restituisce la politica con il suo ETag. Solo persone; agenti e credenziali bearer non hanno alcuna rotta. Impostare required true rientra nel single sign-on, che il piano Enterprise include; un’organizzazione il cui piano ne è privo viene rifiutata con feature_not_in_plan (402). required false è sempre accettato, e Require SSO attivo resta in vigore finché non viene disattivato.

Qualsiasi amministratore designato annulla una rimozione pianificata di Require SSO, che resta quindi in vigore. Se non è pianificata alcuna rimozione non cambia nulla. Risponde con la politica. Solo persone; agenti e credenziali bearer non hanno alcuna rotta.