Provisiona le persone con SCIM

Cosa fa il provisioning

• Ingressi. Assegna una persona all’applicazione nel tuo provider e screenRIG crea il suo account e la rende membro della tua organizzazione. La persona accede tramite single sign-on e non ha password. Non ha alcun progetto finché un gruppo non gliene assegna uno.
• Spostamenti. Un gruppo associato a un progetto dà ai suoi membri quel progetto. Entrare in un gruppo o uscirne aggiunge o rimuove l’accesso.
• Uscite. Disattivare una persona o rimuoverne l’assegnazione termina le sue sessioni e il suo accesso. 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.

Prima di iniziare

• Il single sign-on è configurato e l’organizzazione ha un dominio verificato. Il provisioning crea solo indirizzi dei tuoi domini verificati.
• Sei un amministratore dell’organizzazione.

Attivalo

1. Nelle Impostazioni dell’organizzazione apri Provisioning degli utenti (SCIM) e scegli Attiva il provisioning. Copia l’URL di base, https://api.screenrig.ai/scim/v2. Si trova sull’origine dell’API, non su quella del dashboard.
2. In Token di provisioning scegli Crea token, inserisci un Nome del token (ad esempio Entra) e conferma. Copia subito il token: srscim_ seguito da 43 caratteri, mostrato una sola volta. screenRIG conserva solo un hash.

Attivare il provisioning e creare un token richiedono la tua passkey o password. Una sessione single sign-on vale invece come accesso recente per 10 minuti, quando il tuo provider indica quando la persona si è autenticata; altrimenti il dashboard chiede alla persona di accedere di nuovo presso il provider.

Un’organizzazione può avere fino a cinque token. Per ruotarne uno, crea un nuovo token, incollalo nel tuo provider, poi revoca quello vecchio; il provisioning continua a funzionare. L’elenco mostra quando ogni token è stato usato l’ultima volta. Disattivare il provisioning fa rispondere 403 a ogni richiesta e non cambia l’accesso di nessuno.

Microsoft Entra ID

1. Apri la tua enterprise application (quella che gestisce il single sign-on), scegli Provisioning e imposta Provisioning Mode su Automatic.
2. In Admin Credentials inserisci il base URL come Tenant URL e il token come Secret Token. Scegli Test Connection, poi Save.
3. Apri Mappings, Provision Microsoft Entra ID Users. Mappa userName da userPrincipalName (o da mail quando i tuoi user principal name non sono gli indirizzi con cui le persone accedono), emails[type eq "work"].value da mail, e lascia active sul valore predefinito, Switch([IsSoftDeleted], , "False", "True", "True", "False"). Mantieni gli altri mapping proposti da Entra. screenRIG usa l’email di lavoro, altrimenti l’email principale, altrimenti userName; quell’indirizzo deve appartenere a un dominio verificato ed essere l’indirizzo che il tuo single sign-on invia.
4. Lascia attivo Provision Microsoft Entra ID Groups per concedere l’accesso tramite i gruppi.
5. In Settings imposta Scope su Sync only assigned users and groups, poi assegna le persone e i gruppi in Users and groups.
6. Imposta Provisioning Status su On e salva. Entra esegue un primo ciclo, poi sincronizza circa ogni 40 minuti. Provision on demand sincronizza subito una persona o un gruppo.

Okta

1. Apri la tua applicazione screenRIG. In General modifica App Settings e imposta Provisioning su SCIM.
2. Apri Provisioning, Integration, Edit. Inserisci il base URL come SCIM connector base URL e userName come Unique identifier field for users, seleziona Push New Users, Push Profile Updates e Push Groups e imposta Authentication Mode su HTTP Header. In un’app SCIM personalizzata incolla il token nel campo HTTP Header. Dove Okta chiede un API Token (le app di test SCIM di Okta), inserisci Bearer, uno spazio e il token. Funzionano entrambi. Scegli Test Connector Configuration, poi Save.
3. Apri To App, Edit e abilita Create Users, Update User Attributes e Deactivate Users. Lascia disattivato Sync Password: screenRIG ignora le password.
4. In Sign On imposta Application username format su Email.
5. Assegna le persone e i gruppi in Assignments e invia in Push Groups i gruppi che associ.

Okta disattiva una persona con active: false e non elimina mai.

Gruppi e progetti

I gruppi provisionati sono elencati nelle Impostazioni dell’organizzazione, in Provisioning degli utenti (SCIM), sotto Gruppi sottoposti a provisioning, con il numero dei loro membri e i progetti a cui sono associati. Un gruppo non dà alcun accesso finché una persona che può approvare in un progetto non lo associa:

1. Nel progetto apri Accesso, poi Gruppi. Qualsiasi membro legge le associazioni; il proprietario del progetto, i membri che possono approvare e gli amministratori dell’organizzazione che sono membri associano un gruppo.
2. In Associa un gruppo scegli un Gruppo e un Ruolo: Persona, una semplice appartenenza, oppure Approvatore, che approva anche le revisioni. Scegli Associa gruppo. Rimuovi associazione elimina l’associazione.

Un’associazione può anche limitare ciò che concede a cartelle di schermi e schermi, lo stesso ambito di schermi a cui si può limitare un membro: in Associa un gruppo scegli Intero progetto oppure Limitato agli schermi (un’associazione Approvatore indica solo cartelle). Gli schermi di una persona nel progetto sono l’unione degli ambiti delle sue associazioni, e ogni associazione senza ambito dà l’intero progetto; la persona approva solo dove le sue associazioni Approvatore coprono tutti quegli schermi, quindi essere Approvatore di una cartella e Membro dell’intero progetto fa della persona un semplice membro dell’intero progetto. Il provisioning non riduce mai un accesso concesso a mano e non limita una persona finché sono attivi i client di servizio che ha creato: ogni rifiuto di questo tipo compare nell’attività recente di Provisioning degli utenti, e l’ambito si applica alla sincronizzazione successiva una volta revocati i client. L’ambito di un’associazione è fisso; per cambiarlo, rimuovi l’associazione e associa di nuovo il gruppo.

• Senza ambiti, una persona in più gruppi associati ha il ruolo più alto: Approvatore prevale su Membro.
• Entrare in un gruppo o uscirne aggiunge o rimuove l’appartenenza. Dissociare un gruppo, o eliminarlo nel tuo provider, ritira ciò che aveva concesso.
• Il provisioning rimuove solo ciò che ha aggiunto. Un’appartenenza concessa a mano resta, e un membro che un gruppo ha promosso ad Approvatore torna al ruolo che aveva quando lascia il gruppo.
• Un’organizzazione può avere fino a 200 membri in tutti i suoi progetti, contando ogni persona una sola volta. Una persona che l’organizzazione rifiuta viene registrata come errore negli eventi di provisioning e nient’altro cambia.
• I gruppi concedono solo ruoli di progetto, mai amministratore dell’organizzazione. Gli amministratori vedono le associazioni e i nomi dei progetti, non il contenuto dei progetti.

Chi può essere provisionato

• Un indirizzo di un dominio verificato senza account ne crea uno, senza password.
• Una persona che non ha password né passkey, che la tua organizzazione gestisce, o che si trova in un’organizzazione che richiede il single sign-on, viene presa in carico e accede tramite single sign-on.
• Una persona che ha già un proprio accesso ed è membro di uno dei progetti della tua organizzazione viene collegata solo per l’accesso, a meno che la tua organizzazione non richieda il single sign-on. Il provisioning gestisce il suo accesso ai tuoi progetti e mai il suo nome, la sua email o il suo accesso.
• Chiunque altro viene rifiutato con un errore che indica il motivo: un account con un proprio accesso che non è membro dei tuoi progetti, una persona gestita da un’altra organizzazione e lo staff di screenRIG. Invita prima una persona di questo tipo a uno dei tuoi progetti, e il provisioning la collega poi per l’accesso.

Disattivazione e DELETE

active: false, inviato con PUT o PATCH, e DELETE terminano entrambi l’accesso di una persona. active: true annulla una disattivazione, come indicano le tabelle.

Una persona disattivata da chiunque non sia il tuo provisioning, come lo staff di screenRIG, resta disattivata: active: true fallisce con 400 mutability. Un progetto di proprietà di una persona non viene mai trasferito: una persona collegata ne conserva l’accesso, e il progetto di una persona gestita resta in attesa insieme al resto del suo account fino alla riattivazione. Trasferisci la proprietà del progetto prima di disattivare il proprietario, se altri devono continuare a gestirlo. L’ultimo amministratore dell’organizzazione non può essere disattivato come persona gestita; la richiesta fallisce con 400 mutability, quindi aggiungi prima un altro amministratore.

Riferimento

URL base https://api.screenrig.ai/scim/v2. Il token va in Authorization: Bearer srscim_TOKEN, e viene accettato anche un token da solo. Richieste e risposte sono application/scim+json; application/json è accettato.

I filtri sono da uno a quattro termini attribute eq value uniti da and. Un valore è una stringa tra virgolette, oppure true o false per active. Gli utenti si filtrano su userName (case-insensitive), externalId (esatto), id, emails o emails.value, displayName e active. I gruppi si filtrano su displayName, externalId, id e members o members.value. Tutto il resto dà 400 invalidFilter.

PATCH legge le operazioni nel modo in cui le inviano Entra e Okta, con o senza ?aadOptscim062020. I nomi delle operazioni sono case-insensitive e i booleani sono true, false, "True" o "False". Un’operazione può omettere path o usare chiavi con il punto come {"name.givenName": "Ada"}. I percorsi includono emails[type eq "work"].value, members (add, replace e remove con un array di valori) e members[value eq "<id>"] (remove). Gli attributi che screenRIG non usa vengono accettati e ignorati.

Limiti. Un’organizzazione può inviare 600 richieste al minuto complessivamente con tutti i suoi token, non per indirizzo, perché Entra e Okta condividono gli indirizzi di origine. Oltre il limite la risposta è 429 con Retry-After. Le autenticazioni non riuscite sono limitate a 30 ogni 10 minuti per ciascun indirizzo.

Gli errori usano l’envelope SCIM con scimType, come invalidFilter, uniqueness o mutability:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "409", "scimType": "uniqueness", "detail": "…" }

Provisioning utenti, nelle Impostazioni dell’organizzazione, elenca le ultime 500 richieste, conservate per 30 giorni, compresi gli errori con il loro motivo. Guarda lì per prima cosa quando qualcosa non arriva.

Risoluzione dei problemi

Correlato

• Single sign-on: collega Entra ID, Okta, Google Workspace o un altro provider e rendilo obbligatorio.
• Autenticazione: come accedono gli agenti e come viene approvato l’accesso.
• Riferimento API: le route /scim/v2 e quelle di provisioning.