SSO / SAML Enterprise

Configurare SAML SSO per Tenant

I tenant Enterprise possono configurare SAML SSO tramite l'endpoint POST /api/v1/admin/sso/config. La configurazione richiede:

{
  "idp_entity_id": "https://idp.azienda.com/saml",
  "idp_sso_url": "https://idp.azienda.com/saml/sso",
  "idp_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "verified_domains": ["azienda.com"]
}

Solo un amministratore o proprietario del tenant può attivare SSO. La configurazione viene validata prima dell'archiviazione, verificando che il certificato sia valido e che l'URL SSO sia raggiungibile.

Metadati del Service Provider

Rela AI agisce come Service Provider (SP). I metadati SP sono disponibili su GET /api/v1/admin/sso/config e includono:

Entity ID: https://api.relaai.com/saml/{tenant_id}
ACS URL: https://api.relaai.com/api/v1/admin/sso/callback
Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Questi metadati devono essere configurati nell'Identity Provider (IdP) del tenant.

Il processo di accesso SSO segue questi passaggi:

L'utente accede a POST /api/v1/admin/sso/login con la propria email
Il sistema risolve il tenant dal dominio email
Viene generata una AuthnRequest SAML firmata
L'utente viene reindirizzato all'IdP con la richiesta codificata in Base64
L'utente si autentica presso l'IdP
L'IdP invia la risposta SAML all'ACS URL

Il parametro RelayState viene utilizzato per preservare l'URL di destinazione.

Elaborazione della Risposta SAML

Quando l'IdP risponde all'ACS URL:

La risposta SAML viene decodificata e validata
La firma viene verificata contro il certificato IdP configurato
Vengono estratti gli attributi dell'utente (email, nome, gruppi)
L'utente viene cercato o creato nel sistema (provisioning automatico)
Viene assegnato un ruolo basato sui gruppi SAML mappati
Viene generato un JWT e l'utente viene reindirizzato alla dashboard

Il provisioning automatico crea nuovi utenti con il ruolo member per impostazione predefinita. Gli amministratori possono mappare i gruppi SAML a ruoli specifici.

Verifica del Dominio

Prima di attivare SSO, il tenant deve verificare la proprietà dei propri domini:

Viene generato un token di verifica univoco
L'amministratore aggiunge un record DNS TXT: _relaai-verify.azienda.com
Il sistema verifica il record DNS periodicamente
Una volta verificato, il dominio viene contrassegnato come verified

Solo i domini verificati possono essere utilizzati per SSO. Questo impedisce a un tenant di rivendicare domini che non gli appartengono.

Risoluzione del Tenant per Dominio Email

Il sistema risolve automaticamente il tenant dal dominio dell'email:

utente@azienda.com → dominio "azienda.com" → tenant con quel dominio verificato

Se il dominio non è associato a nessun tenant con SSO attivo, viene utilizzato il flusso di autenticazione standard (email + password).

La risoluzione è case-insensitive e supporta sottodomini se configurati. Più domini possono puntare allo stesso tenant.