Il Single Sign-on (SSO) con SAML 2.0 permette ai tuoi utenti di accedere a deskbird utilizzando il loro provider di identità (IdP) esistente. Qui sotto trovi le opzioni rapide per Okta e Keycloak, oltre a una guida completa alla configurazione della federazione (SSO avviato dal Service Provider).
Stai configurando UDM Plus? User & Data Management (UDM) Plus: setup ti guida passo dopo passo su SSO, la tua HRIS, SCIM e le impostazioni di visibilità nell’ordine corretto.
- SAML con Okta
- SAML con Keycloak
- Configurazione della federazione SAML 2.0
- Rinnovo del certificato SAML
- Quando usare SAML vs. OAuth / OIDC
1. SAML con Okta
Usa la nostra guida dedicata a Okta per configurare un'app SAML su Okta, mappare gli attributi richiesti e testare lo SSO avviato dal Service Provider su deskbird. Include screenshot, dichiarazioni degli attributi e suggerimenti per la risoluzione dei problemi.
👉 Passo dopo passo: configura SAML SSO con Okta
2. SAML con Keycloak
Preferisci usare Keycloak? Segui la guida Keycloak per avviare lo SSO su deskbird.
👉 Passo dopo passo: configura SAML SSO con Keycloak
3. Configurazione della federazione SAML 2.0
SAML 2.0 (Security Assertion Markup Language) è un protocollo basato su XML per scambiare in modo sicuro dati di autenticazione/autorizzazione tra un identity provider (IdP) e un service provider (SP). deskbird supporta lo SSO avviato dal Service Provider (l'autenticazione deve partire da deskbird).
Se vuoi una tile nel tuo launcher IAM (ad es. OneLogin, JumpCloud) su cui gli utenti possono cliccare, aggiungi una Bookmark application che avvia il flusso SP-initiated in deskbird:https://app.deskbird.com/saml?providerName={saml-provider-ID}
L'ID del provider SAML segue il formato saml.{company-name}. Esempio per "Polaroid": https://app.deskbird.com/saml?providerName=saml.polaroid.
Crea una Federation application separata e nascosta nel tuo IdP per la connessione SAML stessa (non visibile agli utenti).
3.1 Configurazione generale
Configura il tuo IdP con i seguenti dettagli del Service Provider di deskbird:
| Service Provider ID (Entity ID) | https://api.deskbird.app/saml/metadata |
| ACS URL (Callback) | https://app.deskbird.com/__/auth/handler |
💡 Per un'autenticazione SAML 2.0 corretta, imposta NameID sull'indirizzo e-mail dell'utente con formato urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
Esempio di snippet di assertion
<saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="<IdP Entity ID>" SPNameQualifier="https://api.deskbird.app/saml/metadata" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> email </saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> </saml2:Subject> Invia a deskbird per la configurazione
| IdP Entity ID | |
| IdP SSO URL | |
| IdP Certificate | Deve iniziare con -----BEGIN CERTIFICATE----- e terminare con -----END CERTIFICATE----- (incolla senza caratteri extra o nuove righe). |
Se hai un file di metadata dell’IdP, puoi semplicemente inviare quello.
3.2 Attributi utente
Attributo richiesto (usa il nome esatto):
| Attributo | Descrizione |
| Indirizzo e-mail UPN usato per l’accesso, le notifiche e le informazioni sulle prenotazioni |
Attributi consigliati:
| Attributo | Descrizione |
| first_name | Nome dell’utente (visualizzato nella piattaforma). Funziona anche il claim predefinito givenname di Microsoft Entra ID. |
| last_name | Cognome dell’utente (visualizzato nella piattaforma). Funziona anche il claim predefinito surname di Microsoft Entra ID. |
| avatar_url | URL dell’immagine del profilo; se omesso vengono usate le iniziali |
| external_id | ID utente IdP per il matching |
| manager_id | ID IdP del manager diretto dell’utente (usato per le approvazioni) |
| locale | Lingua preferita dell’utente (predefinita sulla lingua dell’azienda se omessa) |
| job_title | Ruolo lavorativo dell’utente |
| company_entity | Entità legale dell’utente (predefinita sull’entità aziendale se omessa) |
3.3 Sincronizzazione del nome dal tuo IdP
Se gli utenti vengono creati al primo accesso SAML (senza SCIM o sincronizzazione HRIS), deskbird prende nome e cognome dal tuo IdP e li mantiene sincronizzati:
- Primo accesso: l’utente viene creato con nome e cognome dalla assertion SAML.
- Accessi successivi: se il tuo IdP invia un nome diverso, deskbird lo aggiorna. Questo sostituisce anche i nomi modificati manualmente in deskbird.
- Modifica: mentre il nome viene fornito dal tuo IdP, utenti e admin non possono modificarlo in deskbird (web, iOS e Android). Le modifiche vanno fatte nel tuo IdP e saranno visibili al prossimo accesso dell’utente.
- SCIM o sincronizzazione HRIS: se usi anche uno di questi, la sincronizzazione gestisce il nome e SAML non lo sovrascrive mai.
- Nessun nome inviato: se la assertion non include sia nome che cognome, gli utenti inseriscono il nome durante la configurazione e possono comunque modificarlo.
💡 Solo nome e cognome vengono sincronizzati. Altri attributi, come ufficio o dipartimento, non vengono presi da SAML.
3.4 File di metadata
Dopo aver creato l’applicazione SAML nel tuo IdP, inviaci il file di metadata che includa:
- Certificato
- Entity ID
- SSO URL
4. Rinnovo del certificato SAML
I certificati SAML hanno una data di scadenza (di solito 1–3 anni dopo la creazione). Quando un certificato sta per scadere, il tuo identity provider ti avviserà. È importante rinnovare il certificato prima della scadenza per evitare interruzioni di accesso.
Inizia il processo di rinnovo almeno 2–3 settimane prima della data di scadenza per avere tempo di coordinarti.
Procedura di rinnovo passo dopo passo (Microsoft Entra ID):
- Nel portale Microsoft Entra ID, vai alla tua Enterprise Application di deskbird.
- Vai su Single sign-on > SAML Certificates.
- Clicca sull’icona Edit (matita).
- Clicca su New Certificate.
- Imposta la data di scadenza (il valore predefinito è 3 anni).
- Clicca su Save. Il nuovo certificato apparirà con stato Inactive.
- Scarica il nuovo certificato (formato Base64).
- Invia il certificato all’assistenza deskbird tramite un ticket di supporto. Includi il nome della tua azienda e specifica che si tratta di un rinnovo certificato SAML.
- L’assistenza deskbird sostituirà il certificato dal nostro lato e ti confermerà quando sarà pronto.
- Una volta ricevuta la conferma da deskbird, torna su Entra ID e attiva il nuovo certificato (impostalo su Active).
Interruzioni di servizio
Di solito non ci sono interruzioni durante la rotazione del certificato, purché tu coordini i tempi di attivazione con l’assistenza deskbird. Il vecchio certificato continua a funzionare fino a quando non passi a quello nuovo.
5. Quando usare SAML vs. OAuth / OIDC
Se stai decidendo tra SAML e OAuth (Microsoft SSO), considera quanto segue:
| Funzionalità | SAML 2.0 | OAuth / Microsoft SSO / Google SSO |
|---|---|---|
| Gestione certificati | Richiede rinnovo periodico | Non è necessaria la gestione dei certificati |
| Esperienza utente | Gli utenti cliccano su "Accedi con account aziendale (SSO)" nella schermata di login | Gli utenti cliccano su "Accedi con Microsoft" nella schermata di login |
| Flessibilità IdP | Funziona con qualsiasi IdP SAML 2.0 (Okta, Keycloak, ADFS, ecc.) | Solo Microsoft e Google |
| Requisito del piano | UDM Plus | Disponibile su tutti i piani |