API Enterprise SSO

L’Enterprise SSO (Single Sign-On) consente ai membri dell’organizzazione di autenticarsi usando l’identity provider aziendale esistente anziché un nome utente e una password. Auris supporta sia il protocollo SAML 2.0 che OIDC, basati sul brokering IdP di Keycloak.

Il flusso SSO funziona così:

1. Un admin crea una connessione SSO per un’organizzazione, fornendo la configurazione IdP (metadati SAML o URL discovery OIDC).
2. L’admin aggiunge e verifica uno o più domini email (es. acme-corp.com) tramite record DNS TXT.
3. Una volta attivata la connessione, gli utenti con un’email di dominio verificato vengono automaticamente reindirizzati all’IdP al login.
4. Al primo login SSO, Auris esegue il provisioning JIT (Just-In-Time) — crea l’account utente, lo collega all’organizzazione e emette i token Auris, tutto in modo trasparente.

Tutti gli endpoint SSO admin richiedono l’intestazione x-tenant e un token Bearer valido.

Connessioni SSO

Risposta di successo

{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "name": "Acme Corporate IdP",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml-abc123",
      "domains": ["acme-corp.com", "acme.io"],
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-02-01T14:30:00Z"
    }
  ]
}

Stati della connessione SSO:

Configurazione SAML 2.0

Per SSO basato su SAML, fornisci i metadati dell’Identity Provider. Puoi fornire un metadataUrl (consigliato — Auris lo recupera e analizza automaticamente) o fornire i campi individuali manualmente.

Corpo della richiesta — SAML con URL metadati

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Corpo della richiesta — SAML con configurazione manuale

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----"
  }
}

Configurazione OIDC

Corpo della richiesta — OIDC

{
  "type": "oidc",
  "name": "Acme OIDC Provider",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client-id",
    "clientSecret": "auris-sp-client-secret"
  }
}

Risposta di successo

{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Codici di errore

Attiva e Disattiva

Codici di errore

Verifica Dominio

La verifica del dominio prova che controlli un dominio email prima di abilitare il reindirizzamento automatico SSO per quel dominio. La verifica avviene tramite un record DNS (TXT o CNAME). Una volta verificato un dominio, qualsiasi utente che accede con un indirizzo email su quel dominio viene automaticamente reindirizzato al provider SSO dell’organizzazione.

Risposta di successo

{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z",
      "createdAt": "2025-01-20T10:00:00Z"
    }
  ]
}

Stati di verifica del dominio:

Corpo della richiesta

{
  "domain": "acme-corp.com"
}

Risposta di successo

{
  "ok": true,
  "data": {
    "id": "dom_ghi789",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-mno345pqr678",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-mno345pqr678"
    }
  }
}

Codici di errore

Endpoint SSO Pubblici

Questi endpoint vengono usati dalla pagina di login ospitata di Auris e dall’SDK per eseguire il flusso SSO. Non richiedono autenticazione.

Corpo della richiesta

{
  "email": "[email protected]"
}

Risposta — SSO disponibile

{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/acme-saml-abc123"
  }
}

Risposta — nessun SSO

{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

La risposta è sempre 200 OK indipendentemente dalla configurazione SSO del dominio, per prevenire la divulgazione di informazioni su quali organizzazioni usano SSO.

Questo endpoint è un redirect del browser, non una chiamata API. Il flusso tipico:

1. Il client rileva l’SSO tramite POST /api/auth/sso/detect
2. Il client reindirizza il browser al loginUrl dalla risposta di rilevamento
3. Auris reindirizza alla pagina di login dell’IdP
4. L’utente si autentica presso l’IdP
5. L’IdP reindirizza al callback di Auris
6. Auris emette i token e reindirizza all’URL callback dell’applicazione

Provisioning JIT (Just-In-Time)

Quando un utente si autentica via SSO per la prima volta e non ha ancora un account Auris, Auris automaticamente:

1. Crea un nuovo account utente usando gli attributi dell’assertion SSO (email, nome, cognome)
2. Collega l’utente all’organizzazione proprietaria della connessione SSO
3. Assegna il ruolo membro predefinito (MEMBER)
4. Emette token di accesso e refresh standard di Auris

Ai login successivi, il record utente esistente viene abbinato per email e i token vengono emessi direttamente.

Gestione degli Errori

Se l’assertion SSO non è valida, l’utente viene reindirizzato al callback con parametri di errore:

https://app.tuodominio.com/callback?error=sso_failed&error_description=SAML+assertion+validation+failed&state=original_state

Riferimento Permessi

Note Implementative

Brokering IdP Keycloak: Auris crea e gestisce configurazioni di Identity Provider Keycloak. Ogni connessione SSO corrisponde a un IdP Keycloak con un alias univoco.

Rotazione Certificati: Per le connessioni SAML, aggiorna il campo certificate nella configurazione della connessione quando l’IdP ruota il suo certificato di firma. Auris non rileva automaticamente i cambi di certificato.

Caching Discovery OIDC: Quando si usa OIDC, Auris memorizza nella cache il documento di discovery. La cache scade dopo circa 1 ora.

Correlati

• Guida Enterprise SSO — Configurazione connessioni SAML 2.0 e OIDC
• Single Sign-On — Procedura di integrazione SSO
• Enterprise SSO — Configura le connessioni SSO dalla Console
• API Organizzazioni — Endpoint delle organizzazioni a cui appartengono le connessioni SSO