Aller au contenu principal

OpenID Connect

Cette section décrit la configuration de l'authentification OpenID Connect (OIDC) dans Sync-in.

Sync-in implémente le flux Authorization Code conforme aux recommandations OAuth 2.0 pour les applications web.

La configuration se fait dans environment.yaml, voir la section OIDC.

Prérequis​

Avant d'activer l'OIDC dans Sync-in, un client OAuth/OIDC doit être créé dans votre fournisseur d'identité (IdP).
Les libellés varient selon les fournisseurs, mais la logique est similaire.

Créer une application (client) :​

  • Le type de fournisseur doit être OpenID Connect.
  • Le type de client doit être Confidentiel.
  • Le type d'application doit être Web.
  • Le type de flux (grant) doit être Authorization Code.

Cette configuration permet d'obtenir l'identifiant client (clientId) ainsi que le secret associé (clientSecret) que vous devez reporter dans la configuration.

Configurer les URI de redirection​

Les URI de redirection doivent être déclarées auprès de l'IdP.
Elles permettent à l'IdP de rediriger l'utilisateur vers Sync-in après une authentification réussie.

Connexion depuis un navigateur web​

Pour l'authentification via l'interface web, déclarez l'URI suivante :

  • https://DOMAINE:PORT/api/auth/oidc/callback
info

Cette URI correspond au paramètre de configuration redirectUri.
Elle doit obligatoirement se terminer par /api/auth/oidc/callback.

Connexion depuis les applications de bureau​

Les applications de bureau utilisent le navigateur par défaut du système pour réaliser l'authentification.
Après la connexion, le navigateur redirige l'utilisateur vers une URI locale afin de transmettre le résultat d'authentification à l'application.

Pour autoriser ce fonctionnement, les URI locales suivantes doivent être déclarées :

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

Cette méthode améliore la compatibilité avec les IdP et permet de respecter les mécanismes d'authentification déjà déployés dans les environnements d'entreprise (SSO, MFA, politiques de sécurité, etc.).

info

Lors de l'utilisation d'OIDC, la MFA est censée être appliquée par le fournisseur d'identité. Sync-in n'ajoute pas de challenge 2FA local après le callback OIDC. La 2FA Sync-in reste configurable depuis le profil utilisateur pendant une session OIDC ; les flux d'activation, de réinitialisation et de désactivation vérifient le mot de passe local Sync-in.

Configuration​

Exemple minimal :

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 doit correspondre exactement à l'URI déclarée dans l'IdP.

Flux d'authentification​

Deux méthodes d'authentification sont disponibles sur l'écran de connexion Sync-in.

Authentification locale​

  • Les comptes invités, les comptes administrateurs et les comptes avec des mots de passe d'application peuvent se connecter via leur login / mot de passe.
  • Pour ce flux de connexion, la 2FA locale de Sync-in s'applique lorsqu'elle est activée pour l'utilisateur.
  • Les autres utilisateurs peuvent utiliser leur mot de passe local uniquement si :
    • l'option options.enablePasswordAuth est activée ;
    • ils connaissent leur mot de passe local Sync-in.
  • Cette configuration permet de conserver un accès d'urgence à l'administration sans désactiver l'authentification OIDC.

Pour que cet accès de secours soit utilisable, il est recommandé de configurer et de conserver disponible un mot de passe local Sync-in pour les comptes administrateurs.

Par défaut, l'authentification locale par mot de passe est désactivée pour les utilisateurs OIDC standards. Activez options.enablePasswordAuth uniquement si vous souhaitez explicitement autoriser ce fallback.

Les utilisateurs créés via OIDC commencent avec un mot de passe interne aléatoire. Ils peuvent définir un mot de passe local connu depuis leur profil lorsqu'ils sont authentifiés via OIDC. Ce mot de passe peut ensuite servir à l'authentification locale par mot de passe lorsqu'elle est activée, et au fallback de step-up par mot de passe lorsqu'aucun secret TOTP n'est actif. Il est aussi nécessaire pour activer, réinitialiser ou désactiver la 2FA Sync-in depuis une session navigateur OIDC.

Mots de passe d'application​

La génération et la révocation des mots de passe d'application nécessitent le step-up Sync-in habituel : TOTP lorsqu'il est activé, sinon confirmation par mot de passe local.

Authentification via OpenID Connect (OIDC)​

  • L'utilisateur lance la connexion via le bouton OIDC.
  • Il est redirigé vers l'IdP pour s'authentifier.
  • La MFA, lorsqu'elle est requise, est appliquée par le fournisseur d'identité à cette étape.
  • Après validation, l'utilisateur est automatiquement redirigé vers Sync-in.
  • Sync-in récupère les informations utilisateur et synchronise le compte local.
  • Si aucun compte local n'existe et que autoCreateUser est activée, un compte local est créé avec un mot de passe aléatoire.
  • Le rôle administrateur est appliqué automatiquement si configuré.
  • Le quota de stockage est synchronisé depuis options.storageQuotaClaim lorsque le profil OIDC fournit une valeur valide en octets. Une valeur de claim absente ou 0 définit un stockage illimité.

Le profil OIDC doit fournir une adresse e-mail. Les nouveaux comptes initialisent leur login local depuis preferred_username, puis depuis la partie locale de l'e-mail lorsque preferred_username est absent. Le login est attribué une seule fois et n'est pas renommé lors des connexions OIDC suivantes.

Association du compte et synchronisation​

Sync-in utilise le claim sub validé du token ID comme identité externe stable et le stocke sur le compte utilisateur local. Lors de la connexion, les comptes sont résolus dans cet ordre :

  1. Correspondance de l'identité externe stockée avec le sub du token ID.
  2. Fallback par e-mail uniquement pour les comptes existants qui n'ont pas encore d'identité externe.
  3. Enregistrement du sub inchangé sur ce compte après la première correspondance de compatibilité réussie.
  4. Création d'un nouveau compte local lorsqu'aucune correspondance n'existe et que autoCreateUser est activé.

Une fois un compte associé, les changements d'e-mail côté IdP ne cassent plus la connexion, car Sync-in résout l'utilisateur par sub. Si le login dérivé est déjà utilisé lors de la création automatique d'un compte, Sync-in ajoute un suffixe déterministe dérivé de sub ; la valeur brute de sub n'est pas exposée dans le login.

Pour les utilisateurs existants, Sync-in peut synchroniser l'e-mail, le prénom, le nom, le rôle, le quota de stockage et l'avatar depuis OIDC. Le login local, le mot de passe et les permissions ne sont pas synchronisés après la création du compte.

Rôles administrateurs​

Si options.adminRoleOrGroup est défini, Sync-in vérifie la présence de cette valeur dans les claims groups ou roles retournés par l'IdP. Le rôle administrateur est attribué si une correspondance est trouvée.

Si options.adminRoleOrGroup n'est pas défini, les comptes admin existants conservent leur rôle et ne peuvent pas être rétrogradés via OIDC.

Disponibilité et erreurs​

Les erreurs de configuration ou d'accès à l'IdP entraînent un échec de l'authentification.
En cas d'indisponibilité de l'IdP, seule l'authentification locale reste possible (voir la section Flux d'Authentification).

Sécurité​

Sync-in utilise automatiquement le mécanisme PKCE (Proof Key for Code Exchange) lorsqu'il est pris en charge par le fournisseur d'identité et activé dans la configuration via le paramètre security.supportPKCE (activé par défaut).

PKCE renforce le flux Authorization Code en ajoutant une preuve cryptographique lors de l'échange du code d'autorisation, améliorant la sécurité pour les clients web et natifs.

Cette implémentation s'aligne avec les recommandations de sécurité OAuth actuelles.

info

Le support de PKCE peut empêcher l'authentification avec certains fournisseurs d'identité comme PocketID, auquel cas il peut être désactivé.

L'option security.tokenEndpointAuthMethod prend en charge client_secret_basic et client_secret_post. Utilisez la valeur attendue par votre IdP ; client_secret_basic est la valeur par défaut pour les clients web confidentiels. Le champ clientSecret est requis dans la configuration Sync-in.

La découverte OIDC et les requêtes token exigent HTTPS par défaut. L'option security.allowInsecureRequests ne doit être activée que pour du développement local ou des fournisseurs hérités de confiance.

L'option security.requireVerifiedEmail est activée par défaut. Sync-in exige que le claim UserInfo email_verified soit exactement true avant l'association du compte ou la synchronisation du profil. Désactivez-la uniquement si votre IdP n'expose pas de claim d'e-mail vérifié fiable.

Lorsque options.autoSyncAvatar est activée, Sync-in peut synchroniser l'avatar utilisateur depuis le claim OIDC picture. Les téléchargements d'avatar depuis des plages IP privées ou internes restent bloqués sauf si security.allowPrivateIpAvatarDownload est explicitement activée.