Vai al contenuto principale

OpenID Connect

Questa sezione descrive come configurare l'autenticazione OpenID Connect (OIDC) in Sync-in.

Sync-in implementa il flusso Authorization Code, in conformità alle raccomandazioni OAuth 2.0 per le applicazioni web.

La configurazione si trova in environment.yaml; consultare la sezione OIDC.

Prerequisiti​

Prima di attivare OIDC in Sync-in, è necessario creare un client OAuth/OIDC nel proprio provider di identità (IdP).
Le etichette possono variare in base al provider, ma la logica rimane simile.

Creare un'applicazione (client)​

  • Il tipo di provider deve essere OpenID Connect.
  • Il tipo di client deve essere Confidential.
  • Il tipo di applicazione deve essere Web.
  • Il tipo di grant deve essere Authorization Code.

Questa configurazione fornisce l'ID client (clientId) e il relativo segreto (clientSecret), che devono essere copiati nella configurazione.

Configurare gli URI di reindirizzamento​

Gli URI di reindirizzamento devono essere dichiarati nell'IdP.
Consentono all'IdP di reindirizzare l'utente a Sync-in dopo un'autenticazione riuscita.

Accesso da un browser web​

Per l'autenticazione dall'interfaccia web, dichiarare l'URI seguente:

  • https://DOMINIO:PORTA/api/auth/oidc/callback
informazioni

Questo URI corrisponde al parametro di configurazione redirectUri.
Deve terminare con /api/auth/oidc/callback.

Accesso dalle applicazioni desktop​

Le applicazioni desktop utilizzano il browser predefinito del sistema per eseguire l'autenticazione.
Dopo l'accesso, il browser reindirizza l'utente a un URI locale per trasmettere il risultato dell'autenticazione all'applicazione.

Per consentire questa operazione, dichiarare gli URI locali seguenti:

  • http://127.0.0.1:49152/oidc/callback
  • http://127.0.0.1:49153/oidc/callback
  • http://127.0.0.1:49154/oidc/callback

Questo approccio migliora la compatibilità con gli IdP e corrisponde ai meccanismi di autenticazione già adottati negli ambienti aziendali (SSO, MFA, politiche di sicurezza e così via).

informazioni

Quando si utilizza OIDC, si presume che l'MFA venga applicata dal provider di identità. Sync-in non aggiunge una verifica 2FA locale dopo il callback OIDC. La 2FA di Sync-in resta configurabile dal profilo utente durante una sessione OIDC; le procedure di attivazione, reimpostazione e disattivazione verificano la password locale di Sync-in.

Configurazione​

Esempio minimo:

auth:
  provider: oidc
  oidc:
    issuerUrl: 'https://auth.example.com/realms/my-realm'
    clientId: 'OIDCClientId'
    clientSecret: 'OIDCClientSecret'
    redirectUri: 'https://sync-in.domain.com/api/auth/oidc/callback'

⚠️ redirectUri deve corrispondere esattamente all'URI dichiarato nell'IdP.

Flusso di autenticazione​

Nella schermata di accesso di Sync-in sono disponibili due metodi di autenticazione.

Autenticazione locale​

  • Gli account ospite, gli account amministratore e gli account dotati di password per applicazioni possono accedere con il proprio nome utente e la propria password.
  • Per questo percorso di accesso, la 2FA locale di Sync-in viene applicata quando è attiva per l'utente.
  • Gli altri utenti possono utilizzare la propria password locale soltanto se:
    • options.enablePasswordAuth è attivo;
    • conoscono la propria password locale di Sync-in.
  • Questa configurazione mantiene l'accesso amministrativo di emergenza senza disattivare l'autenticazione OIDC.

Affinché questo accesso di emergenza sia utilizzabile, è consigliabile configurare e mantenere disponibile una password locale Sync-in per gli account amministratore.

Per impostazione predefinita, l'autenticazione tramite password locale è disattivata per gli utenti OIDC standard. Attivare options.enablePasswordAuth soltanto se si desidera consentire esplicitamente questo fallback.

Gli utenti creati tramite OIDC ricevono inizialmente una password interna casuale. Durante una sessione autenticata tramite OIDC, possono impostare dal proprio profilo una password locale nota. Questa password può quindi essere utilizzata per l'autenticazione locale, quando attiva, e per la verifica aggiuntiva tramite password quando non è presente alcun segreto TOTP. È inoltre necessaria per attivare, reimpostare o disattivare la 2FA di Sync-in da una sessione OIDC nel browser.

Password per applicazioni​

La generazione e la revoca delle password per applicazioni richiedono la consueta verifica aggiuntiva di Sync-in: TOTP, quando attivo, oppure la conferma della password locale.

Autenticazione OpenID Connect (OIDC)​

  • L'utente avvia l'accesso tramite il pulsante OIDC.
  • Viene reindirizzato all'IdP per autenticarsi.
  • L'MFA, quando richiesta, viene applicata dal provider di identità durante questa fase.
  • Dopo la convalida, l'utente viene reindirizzato automaticamente a Sync-in.
  • Sync-in recupera le informazioni dell'utente e sincronizza l'account locale.
  • Se non esiste alcun account locale e autoCreateUser è attivo, viene creato un account locale con una password casuale.
  • Il ruolo di amministratore viene applicato automaticamente, se configurato.
  • La quota di archiviazione viene sincronizzata dal claim options.storageQuotaClaim quando il profilo OIDC fornisce un valore valido in byte. Un claim assente o con valore 0 imposta uno spazio di archiviazione illimitato.

Il profilo OIDC deve fornire un indirizzo e-mail. Per i nuovi account, il login locale viene inizializzato da preferred_username oppure, quando preferred_username è assente, dalla parte locale dell'indirizzo e-mail. Il login viene assegnato una sola volta e non viene rinominato durante gli accessi OIDC successivi.

Associazione e sincronizzazione degli account​

Sync-in utilizza il claim sub del token ID convalidato come identità esterna stabile e lo memorizza nell'account utente locale. Durante l'accesso, gli account vengono risolti nell'ordine seguente:

  1. Confronto dell'identità esterna memorizzata con il claim sub del token ID.
  2. Ricerca per e-mail soltanto per gli account esistenti che non dispongono ancora di un'identità esterna.
  3. Memorizzazione del claim sub invariato nell'account dopo la prima corrispondenza di compatibilità riuscita.
  4. Creazione di un nuovo account locale quando non viene trovata alcuna corrispondenza e autoCreateUser è attivo.

Dopo l'associazione di un account, le modifiche dell'indirizzo e-mail nell'IdP non interrompono più l'accesso, perché Sync-in risolve l'utente tramite sub. Se il login derivato è già utilizzato durante la creazione automatica dell'account, Sync-in aggiunge un suffisso deterministico derivato da sub; il valore grezzo di sub non viene esposto nel login.

Per gli utenti esistenti, Sync-in può sincronizzare da OIDC l'indirizzo e-mail, il nome, il cognome, il ruolo, la quota di archiviazione e l'avatar. Il login locale, la password e le autorizzazioni non vengono sincronizzati dopo la creazione dell'account.

Ruoli di amministratore​

Se options.adminRoleOrGroup è impostato, Sync-in verifica se questo valore è presente nei claim groups o roles restituiti dall'IdP. Il ruolo di amministratore viene assegnato quando viene trovata una corrispondenza.

Se options.adminRoleOrGroup non è impostato, gli account amministratore esistenti mantengono il proprio ruolo e non possono essere retrocessi tramite OIDC.

Disponibilità ed errori​

Gli errori di configurazione o di accesso all'IdP causano il fallimento dell'autenticazione.
Se l'IdP non è disponibile, rimane possibile soltanto l'autenticazione locale (consultare Flusso di autenticazione).

Sicurezza​

Sync-in utilizza automaticamente il meccanismo PKCE (Proof Key for Code Exchange) quando è supportato dal provider di identità e attivato nella configurazione tramite il parametro security.supportPKCE, attivo per impostazione predefinita.

PKCE rafforza il flusso Authorization Code aggiungendo una prova crittografica durante lo scambio del codice di autorizzazione, migliorando la sicurezza dei client web e nativi.

Questa implementazione è conforme alle attuali raccomandazioni di sicurezza OAuth.

informazioni

Il supporto PKCE può impedire l'autenticazione con alcuni provider di identità, come PocketID; in tal caso può essere disattivato.

L'opzione security.tokenEndpointAuthMethod supporta client_secret_basic e client_secret_post. Utilizzare il valore previsto dall'IdP; client_secret_basic è il valore predefinito per i client web riservati. Il campo clientSecret è obbligatorio nella configurazione di Sync-in.

Il meccanismo di discovery OIDC e le richieste di token richiedono HTTPS per impostazione predefinita. L'opzione security.allowInsecureRequests deve essere attivata soltanto per lo sviluppo locale o per provider legacy attendibili.

L'opzione security.requireVerifiedEmail è attiva per impostazione predefinita. Prima di associare un account o sincronizzare un profilo, Sync-in richiede che il claim UserInfo email_verified sia esattamente true. Disattivare questa opzione soltanto se l'IdP non espone un claim affidabile per l'indirizzo e-mail verificato.

Quando options.autoSyncAvatar è attivo, Sync-in può sincronizzare l'avatar dell'utente dal claim OIDC picture. I download di avatar da intervalli IP privati o interni restano bloccati, a meno che security.allowPrivateIpAvatarDownload non venga attivato esplicitamente.