LIVE · CATENA D'AUDIT · UE
SISTEMA · 99,99% UPTIME
v 1.0 ↗ FATTO IN UE

Configurazione SSO

Configura il single sign-on OIDC o SAML 2.0 per la tua organizzazione NexBasira.

Configurazione SSO

NexBasira supporta sia OpenID Connect (OIDC) sia SAML 2.0 Web Browser SSO. Gli utenti nei domini email configurati vengono autenticati tramite il tuo provider di identità; i primi accessi ottengono il provisioning just-in-time con il ruolo di default che scegli.

Prima di iniziare

  • Ti serve un ruolo org_admin sul lato NexBasira.
  • Ti serve l'accesso all'admin del tuo IdP per registrare un'applicazione + configurare il mapping degli attributi.
  • L'SSO è disponibile dal piano Pro in su (vedi prezzi).

Walkthrough OIDC

1. Trova il tuo callback URL

Nella SPA di NexBasira: Admin → SSO → Protocollo: OpenID Connect. Il callback URL è mostrato in cima al modulo:

https://app.nexbasira.com/api/v1/auth/sso/callback

I clienti con dominio personalizzato (Pro+) vedono qui il proprio dominio. Copialo — al tuo IdP serve.

2. Registra un'applicazione nel tuo IdP

Ogni IdP ha la propria UI, ma la forma è la stessa:

  • Tipo di applicazione: Web (server-side, confidential client)
  • Redirect URI: il callback URL dello step 1
  • Grant type consentiti: Authorization Code (con PKCE)
  • Scope: openid + email + profile

L'IdP ti restituisce un Client ID, un Client Secret e l'Issuer URL (l'URL base per la discovery — di solito https://your-idp.example.com/realms/yourrealm oppure https://accounts.google.com).

3. Compila la configurazione SSO

Di nuovo in Admin → SSO, compila il modulo:

  • Nome visualizzato: mostrato sul pulsante "Continua con SSO". Es. "Acme SSO".
  • Issuer URL: dal tuo IdP.
  • Client ID + Client Secret dal tuo IdP.
  • Domini email: elenco separato da virgole (acme.com, acme-eu.com). Gli utenti con email in questi domini vengono instradati tramite SSO.
  • Ruolo di default per i nuovi utenti: di solito inspector. Gli admin dell'org devono ottenere il ruolo org_admin manualmente dopo il primo accesso.
  • Auto-provisioning dei nuovi utenti al primo accesso: tipicamente attivo.
  • Abilitato: disattivo finché non hai testato.

4. Testa la discovery

Clicca Testa discovery. Recupera la configurazione OpenID del tuo IdP ({issuer_url}/.well-known/openid-configuration) + effettua il parsing del JWKS. Errori comuni:

  • OK — N chiavi JWKS: hai finito.
  • Connection refused / DNS failure: errore di battitura nell'issuer URL; verifica che si risolva nel tuo browser.
  • JSON parse error: l'issuer URL punta a qualcosa che non è un provider OIDC.
  • No JWKS keys: la probe è riuscita ma l'endpoint JWKS ha restituito un set vuoto; controlla la rotazione delle chiavi lato IdP.

5. Abilita + smoke-test

Attiva Abilitato, salva. Esci, poi accedi con un'email di uno dei domini consentiti. Dovresti essere reindirizzato alla schermata di login del tuo IdP, poi di nuovo alla dashboard della SPA.

Walkthrough SAML 2.0

1. Trova il tuo ACS URL

In Admin → SSO → Protocollo: SAML 2.0, copia l'URL dell'Assertion Consumer Service:

https://app.nexbasira.com/api/v1/auth/saml/acs

2. Registra un'app SAML nel tuo IdP

  • ACS URL / Reply URL: l'URL dello step 1.
  • Entity ID (audience): https://app.nexbasira.com/saml/sp (o il tuo dominio personalizzato).
  • Formato NameID: emailAddress.
  • Mapping degli attributi: almeno email; idealmente anche givenName + surname.
  • Firma le asserzioni: obbligatorio.

L'IdP ti restituisce un Entity ID, un SSO Service URL e un certificato di firma (PEM).

3. Compila la configurazione SAML

  • IdP Entity ID — dal tuo IdP.
  • IdP SSO Service URL — dal tuo IdP.
  • Certificato di firma IdP (PEM) — incolla l'intero blocco -----BEGIN CERTIFICATE-----.
  • Domini email — stessa forma di OIDC.
  • Ruolo di default + auto-provisioning — come per OIDC.

La sezione Avanzate — mapping degli attributi ti permette di sovrascrivere le URN che cerchiamo; i default corrispondono alla convenzione WS-Federation di Microsoft, che la maggior parte degli IdP rispetta out of the box.

4. Abilita + smoke-test

Stesso flusso di OIDC: attiva Abilitato, esci, accedi con un'email di un dominio consentito, aspettati un round-trip attraverso il tuo IdP.

IdP testati

Il supporto OIDC + SAML di NexBasira è generico; qualsiasi IdP conforme alle specifiche funziona. Abbiamo fatto smoke test su:

  • Microsoft Entra ID (Azure AD) — OIDC + SAML
  • Google Workspace — OIDC + SAML
  • Okta — OIDC + SAML
  • Keycloak — OIDC + SAML
  • OneLogin — SAML

Regole di provisioning JIT

  • La prima volta che un utente con un dominio corrispondente accede tramite SSO, viene creata una Membership con il ruolo di default configurato.
  • email è la chiave univoca. Un utente che cambia la propria email nell'IdP crea un nuovo account.
  • I cambi di ruolo dopo il primo accesso si gestiscono nella SPA (Admin → Membri), non nell'IdP. Per il mapping gruppo → ruolo guidato dall'IdP, vedi provisioning SCIM.

Disabilitare l'SSO

Puoi disattivare Abilitato (mantiene la configurazione; puoi riabilitarla più tardi) oppure cliccare Rimuovi SSO (elimina la configurazione). Con l'SSO disabilitato, tutti gli utenti tornano all'autenticazione con password; le membership esistenti vengono preservate.

Risoluzione dei problemi

SintomoCausa probabile
Loop di redirect tra IdP + SPAIl dominio email non è nell'allowlist. L'email dell'utente non corrisponde.
"Signature validation failed" (SAML)Certificato di firma obsoleto nella configurazione. Reincollalo dall'IdP.
"Issuer mismatch" (SAML)L'Entity ID nell'IdP non corrisponde a quello che ci aspettiamo. Controlla maiuscole/minuscole e lo slash finale.
"No email attribute in assertion"Il mapping degli attributi SAML nell'IdP non emette l'email. Sovrascrivi la URN nelle impostazioni Avanzate.

Cosa c'è dopo