Fai accedere le persone con il tuo provider di identità

Cosa fa

• Una connessione per organizzazione. Un amministratore dell’organizzazione la configura nelle Impostazioni dell’organizzazione del dashboard, in Single sign-on.
• I tuoi domini decidono chi lo usa. La pagina di accesso chiede prima l’email. Un indirizzo di uno dei tuoi domini verificati prosegue verso il tuo provider.
• Il tuo provider decide chi entra. Una persona il cui indirizzo non è usato da nessun account viene creata al primo accesso, a meno che tu non disattivi Create accounts at first sign-in nella connessione. Una nuova persona non ha alcun progetto finché un invito o un gruppo provisionato non gliene assegna uno.
• Le tue persone sono membri. Una persona che accede tramite il tuo provider è un membro della tua organizzazione. Solo il tuo provider la rimuove.
• Require single sign-on rifiuta le password e le passkey sui tuoi domini.

Prima di iniziare

• Sei un amministratore dell’organizzazione.
• L’organizzazione ha un dominio verificato. Nelle Impostazioni dell’organizzazione, in Domini verificati, inseriscilo in Aggiungere un dominio, scegli Ottenere record DNS, pubblica il record TXT mostrato, poi scegli Verificare example.com (con il tuo dominio al suo posto). Lascia il record al suo posto: screenRIG lo controlla ogni giorno e rimuove un dominio il cui record resta assente per 7 giorni, e il single sign-on si interrompe per i suoi indirizzi.
• Le modifiche alla connessione richiedono la tua passkey o password. Una sessione single sign-on vale invece come accesso recente per 10 minuti, ma solo quando il tuo provider indica quando la persona si è autenticata (auth_time in OpenID Connect, AuthnInstant in SAML). Altrimenti screenRIG chiede alla persona di accedere di nuovo presso il provider prima della modifica.

Il tuo provider richiede questi valori:

Ogni connessione ha il proprio redirect URI, perché il connection ID fa parte dell’indirizzo. Dopo aver salvato una connessione, le impostazioni di Single sign-on nelle Impostazioni dell’organizzazione mostrano il valore esatto di ciascuno in Valori per il tuo provider di identità, con il tuo connection ID già inserito.

Microsoft Entra ID

Il preset Entra fa accedere le persone di un tenant tramite OpenID Connect.

1. Nel Microsoft Entra admin center apri App registrations e scegli New registration. Dagli un nome e scegli Accounts in this organizational directory only. Lascia vuoto il redirect URI: lo aggiunge il passaggio 6.
2. Apri Certificates & secrets, crea un client secret e copia subito il suo Value, non il suo ID.
3. Apri Token configuration, scegli Add optional claim, scegli il tipo ID e aggiungi email e, accanto, auth_time. Senza auth_time Entra non indica quando la persona si è autenticata, e un’azione sensibile rimanda la persona a Entra per accedere di nuovo (vedi Cosa vedono le persone).
4. In Overview copia l’Application (client) ID e il Directory (tenant) ID.
5. Nelle Impostazioni dell’organizzazione, in Single sign-on, scegli Configura il single sign-on, poi Microsoft Entra ID. Inserisci un Nome, che le persone vedono nella pagina di accesso, il Tenant ID, il Client ID e il Segreto client, e scegli Salva connessione.
6. In Valori per il tuo provider di identità copia il Redirect URI, https://screenrig.ai/api/sso/oidc/CONNECTION_ID/callback con il tuo connection ID. In Entra apri Authentication, aggiungi la piattaforma Web (non Single-page application: lo scambio del codice avviene sul nostro server) e inserisci il valore.
7. Esegui un test sign-in.

screenRIG riconosce una persona dal suo object ID di Entra, mai dall’email o dallo user principal name, che gli amministratori di Entra possono modificare: rinominare un utente ne conserva l’account. I token di qualsiasi altro tenant vengono rifiutati. screenRIG legge l’indirizzo dal claim email e, per un tenant Entra, ricorre a preferred_username quando email è assente; il claim opzionale del passaggio 3 fa sì che sia l’indirizzo mail della persona. Entra non invia email_verified, quindi screenRIG accetta l’indirizzo perché appartiene a un dominio che hai verificato. Entra consente l’accesso a ogni utente del tenant, a meno che Assignment required dell’enterprise application non sia Yes.

Okta e altri provider OpenID Connect

Questa opzione è adatta a Okta, Auth0, Keycloak e a qualsiasi provider con un documento di discovery in /.well-known/openid-configuration.

1. Nel provider crea un’applicazione web che usa il flusso authorization code. In Okta scegli Applications, Create App Integration, OIDC, Web Application. Il provider può chiedere un redirect URI prima che screenRIG ne abbia uno per te: inserisci ora un qualsiasi indirizzo https e sostituiscilo al passaggio 4. Assegna le persone o i gruppi che possono accedere.
2. Copia il client ID, il client secret e l’issuer, l’indirizzo https indicato dal documento di discovery. Per Okta è l’org URL, come https://example.okta.com, oppure l’indirizzo di un server di autorizzazione personalizzato.
3. Nelle Impostazioni dell’organizzazione, in Single sign-on, scegli Configura il single sign-on, poi OpenID Connect. Inserisci un Nome, l’Issuer, il Client ID e il Segreto client, e scegli Salva connessione.
4. In Valori per il tuo provider di identità copia il Redirect URI, https://screenrig.ai/api/sso/oidc/CONNECTION_ID/callback con il tuo connection ID, e inseriscilo come redirect URI dell’applicazione presso il provider.
5. Esegui un test sign-in.

Il provider deve supportare PKCE con S256, la modalità di risposta form_post e gli ID token firmati con un algoritmo asimmetrico, e deve consentire gli scope openid, email e profile. Il suo ID token deve contenere un claim email: solo un tenant Entra ricorre a un altro claim. Un claim email_verified, se inviato, deve essere true. Invia un claim auth_time dove il provider può: è così che screenRIG scopre quando la persona si è autenticata.

SAML 2.0

Questa opzione è adatta a un’enterprise application di Entra, a Okta, a Google Workspace e a qualsiasi altro provider SAML 2.0. Inizia dal provider, poi inserisci i suoi metadati in screenRIG, che mostra i valori di cui il provider ha bisogno.

screenRIG richiede che ogni risposta soddisfi queste condizioni:

• La risposta contiene esattamente un’asserzione, e non è cifrata.
• L’asserzione stessa è firmata con RSA o ECDSA e SHA-256 o un algoritmo più forte. SHA-1 viene rifiutato, così come una risposta firmata che contiene un’asserzione non firmata.
• L’issuer dell’asserzione è l’entity ID del tuo provider, e la sua restrizione di audience indica l’entity ID di screenRIG.
• L’accesso parte da screenRIG. Un riquadro nel portale delle app del tuo provider (accesso avviato dall’IdP) viene rifiutato; le persone partono dalla pagina di accesso di screenRIG.
• Gli orologi differiscono di non più di 3 minuti e ogni asserzione viene usata una sola volta.
• Il NameID è presente, nel formato persistent, indirizzo email o unspecified. Un NameID transient, o di qualsiasi altro formato, viene rifiutato. Il NameID è l’identificatore della persona in screenRIG; per Entra è l’attributo object ID.
• L’email arriva come attributo email, mail, urn:oid:0.9.2342.19200300.100.1.3, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress o http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn, oppure come NameID in formato email.

Entra ID

1. Apri Enterprise applications, New application, Create your own application e scegli Integrate any other application you don't find in the gallery.
2. Apri Single sign-on e scegli SAML. In SAML Certificates scarica il Federation Metadata XML e imposta Signing Option su Sign SAML assertion o Sign SAML response and assertion.
3. Nelle Impostazioni dell’organizzazione, in Single sign-on, scegli Configura il single sign-on, poi SAML 2.0. Inserisci un Nome, incolla i metadati XML in Documento dei metadati e scegli Salva connessione. Valori per il tuo provider di identità mostra poi l’Entity ID e l’Indirizzo assertion consumer service (ACS).
4. In Entra modifica Basic SAML Configuration: Identifier è l’entity ID e Reply URL è l’indirizzo ACS.
5. Lascia i claim predefiniti: contengono l’object ID e l’indirizzo email della persona. Controlla che le persone che assegni abbiano un indirizzo email.
6. Assegna le persone in Users and groups, poi esegui un test sign-in.

Le persone che hanno già effettuato l’accesso tramite OpenID Connect mantengono i loro account quando un tenant passa a SAML, e viceversa: entrambi i protocolli identificano una persona dal tenant e dall’object ID di Entra. La risposta SAML deve contenere il claim object identifier, che è tra i claim predefiniti di Entra. Senza di esso screenRIG ricorre al NameID, e un account collegato tramite OpenID Connect non corrisponde più (subject_mismatch).

Okta

1. Scegli Applications, Create App Integration, SAML 2.0. Okta chiede Single sign-on URL e Audience URI prima di mostrare i suoi metadati: inserisci ora un qualsiasi indirizzo https per entrambi.
2. Imposta Name ID format su Persistent e Application username su Email, e aggiungi l’attribute statement email con il valore user.email. In Show Advanced Settings lascia Assertion Signature su Signed con Signature Algorithm RSA-SHA256 e Digest Algorithm SHA256, e Assertion Encryption disattivato.
3. Fai clic su Finish, apri la scheda Sign On e copia l’Identity Provider metadata.
4. Nelle Impostazioni dell’organizzazione, in Single sign-on, scegli Configura il single sign-on, poi SAML 2.0. Inserisci un Nome, incolla i metadati in Documento dei metadati e scegli Salva connessione. Copia l’Entity ID e l’Indirizzo assertion consumer service (ACS) da Valori per il tuo provider di identità.
5. In Okta modifica SAML Settings: Single sign-on URL è l’indirizzo ACS e Audience URI è l’entity ID.
6. Assegna le persone, poi esegui un test sign-in.

Google Workspace

1. Nella Admin console apri Apps, Web and mobile apps, Add app e scegli Add custom SAML app. Dagli un nome.
2. Scarica i metadati del Google Identity Provider e continua.
3. Nelle Impostazioni dell’organizzazione, in Single sign-on, scegli Configura il single sign-on, poi SAML 2.0. Inserisci un Nome, incolla i metadati in Documento dei metadati e scegli Salva connessione. Copia l’Entity ID e l’Indirizzo assertion consumer service (ACS) da Valori per il tuo provider di identità.
4. In Google inserisci l’indirizzo ACS e l’entity ID. Imposta Name ID format su PERSISTENT e Name ID su Basic Information, Primary email. Lascia Signed response deselezionato: Google firma allora l’asserzione, come richiede screenRIG.
5. Mappa l’attributo Primary email di Google Directory sull’attributo dell’app email.
6. Apri User access dell’app e attivalo per le persone che accedono, poi esegui un test sign-in.

Ruota un certificato

Una connessione considera attendibili fino a quattro certificati di firma, così la rotazione avviene senza interruzioni. Incolla il nuovo certificato accanto a quello vecchio (oppure incolla i nuovi metadati del provider, che li elencano entrambi) e salva, passa il provider al nuovo certificato, poi rimuovi quello vecchio.

Test sign-in

Premi Accesso di prova nelle Impostazioni dell’organizzazione. Accedi dal tuo provider e torni al dashboard, che mostra l’indirizzo inviato dal provider e se ha inviato un identificatore stabile. Un test non fa accedere nessuno. Un test non riuscito mostra il messaggio di uno dei codici di errore. L’indirizzo deve appartenere a un dominio verificato.

Un test riuscito, o un accesso reale, con il provider, il tenant, l’entity ID e il protocollo attuali della connessione è ciò che ti permette di rendere obbligatorio il single sign-on.

Require single sign-on

Scegli Richiedi il single sign-on nelle Impostazioni dell’organizzazione dopo un test riuscito, seleziona gli amministratori di emergenza e conferma. Per tutte le persone dei tuoi domini verificati:

• La pagina di accesso offre solo il tuo provider. Una password o una passkey viene rifiutata con sso_required. Password e passkey restano sull’account, inutilizzate, e funzionano di nuovo se disattivi il requisito.
• Un account esistente il cui indirizzo verificato appartiene al tuo dominio accede allo stesso account al primo single sign-on, qualunque metodo di accesso abbia, e conserva i propri progetti. La tua organizzazione lo gestisce da quel momento: la sua email segue il tuo provider a ogni accesso e la persona non può modificarla.
• Amministratori di emergenza. Scegli fino a due amministratori dell’organizzazione che hanno una passkey. Mantengono l’accesso con passkey per il giorno in cui il tuo provider è fuori servizio, e ogni accesso di questo tipo viene registrato. Modifica gli amministratori di emergenza cambia la scelta in seguito.
• Finché il requisito è attivo, l’issuer, il tenant ID, l’entity ID e il protocollo della connessione non possono cambiare e la connessione non può essere rimossa. I certificati e il client secret possono essere ruotati.

Disattivarlo richiede 72 ore. Scegli Turn off requirement: il requisito resta in vigore fino ad allora, ogni amministratore riceve un’email e qualsiasi amministratore può scegliere Cancel removal.

Cosa vedono le persone

• La pagina di accesso chiede prima l’email e prosegue verso il tuo provider. La risposta dipende solo dal dominio, quindi non mostra se una persona ha un account.
• Una sessione dura 24 ore dall’accesso a screenRIG e l’uso non la prolunga. Dopo 12 ore il dashboard la rinnova in modo silenzioso alla pagina successiva, e dopo la fine di una sessione esegue di nuovo l’accesso nello stesso modo. Un avvio silenzioso non invia alcun login hint, quindi il provider risponde per l’account di cui ha una sessione; se è un’altra persona, il rinnovo fallisce con subject_mismatch. Una persona con una sessione attiva presso il provider non digita nulla; altrimenti accede di nuovo.
• Un’azione che richiede una passkey o una password, come la modifica della connessione, accetta invece una sessione single sign-on, che vale come accesso recente per 10 minuti. Vale solo quando il tuo provider indica quando la persona si è autenticata: l’ora del provider stesso (auth_time in OpenID Connect, AuthnInstant in SAML), non quella dell’accesso a screenRIG. Quando il provider non indica alcuna ora, o ne indica una più vecchia di 10 minuti, screenRIG chiede alla persona di accedere di nuovo presso il provider: il dashboard fa passare la persona dal provider per una nuova autenticazione e la riporta dov’era.
• Una persona che il tuo provider disabilita perde l’accesso entro 24 ore, e subito con il provisioning utenti. Gli agenti e i grant OAuth approvati da una persona continuano a funzionare finché la persona non viene disattivata, dal provisioning utenti o dallo staff di screenRIG: rendere obbligatorio il single sign-on e disabilitare la persona presso il tuo provider non li terminano.

Collega un account esistente

Una persona del tuo dominio verificato che ha già un account screenRIG con password o passkey non accede a quell’account con un primo single sign-on (account_exists), a meno che tu non renda obbligatorio il single sign-on. Accede come prima, apre Profilo e accesso all’indirizzo https://screenrig.ai/dashboard/me, sceglie Collega il single sign-on e accede dal provider. Da quel momento il single sign-on apre lo stesso account, che mantiene i propri metodi di accesso. Profilo e accesso offre il collegamento a ogni persona del tuo dominio che ha effettuato l’accesso e non ha ancora eseguito il collegamento.

Risoluzione dei problemi

Un accesso non riuscito torna alla pagina di accesso con il codice nell’indirizzo (#sso_error=CODE). Un test non riuscito mostra nella connessione il messaggio del suo codice.

Correlato

• Provisioning utenti: crea, aggiorna e rimuovi le persone dal tuo provider e dai ai gruppi l’accesso ai progetti.
• Autenticazione: come accedono gli agenti e come viene approvato l’accesso.
• Riferimento API: le route di connessione, policy e accesso.