OpenID Connect Nextcloud : configurer user_oidc

Nextcloud user_oidc permet de confier la connexion des utilisateurs à un fournisseur d'identité compatible OpenID Connect. L'utilisateur s'authentifie auprès de ce service, puis Nextcloud valide le retour, associe une identité locale et ouvre la session. La difficulté se situe moins dans l'installation de l'application que dans le choix de l'identifiant, du provisionnement et des groupes.

Ce guide décrit la configuration de l'application user_oidc avec un fournisseur OIDC externe. Il explique aussi comment éviter les comptes en double, conserver un accès administrateur de secours et tester le flux avant de l'ouvrir à toute l'organisation.

À quoi sert user_oidc dans Nextcloud ?

L'application user_oidc transforme Nextcloud en client OpenID Connect. Le fournisseur d'identité, souvent abrégé IdP, réalise l'authentification. Il peut appliquer ses propres règles, par exemple une authentification multifacteur ou une restriction d'accès. Nextcloud reçoit ensuite un jeton d'identité, vérifie sa signature et utilise les claims, c'est-à-dire les attributs du jeton, pour retrouver ou créer le compte local.

Cette architecture ne doit pas être confondue avec le fournisseur OAuth2 intégré à Nextcloud :

Le guide SSO et LDAP Nextcloud aide à choisir l'architecture d'identité. Le guide OAuth2 avec Nextcloud couvre le sens opposé, lorsque Nextcloud autorise une application cliente. Pour replacer ces briques dans la plateforme, commencez par le guide Nextcloud.

Quels prérequis préparer avant de créer le fournisseur ?

Réunissez d'abord les éléments suivants :

• une instance Nextcloud servie en HTTPS avec une URL stable ;
• un fournisseur compatible avec la découverte OpenID Connect ;
• l'URL du document de découverte, souvent terminée par /.well-known/openid-configuration ;
• un identifiant de client et un secret créés pour cette instance Nextcloud ;
• les claims réellement émis dans le jeton ou par l'endpoint userinfo ;
• un compte administrateur local de secours, testé avant toute redirection automatique ;
• un compte pilote sans privilège et, si besoin, un second compte situé hors des groupes autorisés.

Le document de découverte annonce notamment les endpoints d'autorisation, de jeton et de clés publiques. Ne recopiez pas ces adresses depuis un exemple trouvé ailleurs. Utilisez l'URL propre à votre tenant ou à votre domaine IdP, puis ouvrez-la pour vérifier qu'elle renvoie bien un document JSON cohérent.

Installez l'application depuis le catalogue Nextcloud ou selon le processus de déploiement validé pour votre instance. La page Administration > OpenID Connect affiche l'URI de redirection à déclarer côté IdP. Copiez cette valeur exacte. Selon la configuration des URL Nextcloud, elle ressemble généralement à :

https://cloud.example.com/index.php/apps/user_oidc/code

Une différence de schéma, de domaine, de sous-dossier ou de slash peut suffire à provoquer une erreur redirect_uri_mismatch. Si Nextcloud se trouve derrière un reverse proxy, vérifiez aussi qu'il génère son URL publique en HTTPS et avec le bon nom d'hôte.

Comment créer le fournisseur OIDC dans Nextcloud ?

Dans l'interface d'administration, ajoutez un fournisseur puis renseignez au minimum :

• un identifiant administratif, par exemple entreprise ;
• le client ID remis par l'IdP ;
• le client secret ;
• l'endpoint de découverte ;
• les scopes demandés, avec openid email profile comme valeur par défaut de l'application.

Le client secret doit rester hors des tickets, captures et dépôts Git. Pour une configuration automatisée, la commande occ user_oidc:provider accepte le secret directement, depuis un fichier ou depuis une variable d'environnement. La lecture depuis un fichier évite de le placer dans la ligne de commande :

sudo -u www-data php occ user_oidc:provider entreprise \
  --clientid="nextcloud-production" \
  --clientsecret-file="/run/secrets/nextcloud-oidc-client-secret" \
  --discoveryuri="https://idp.example.com/.well-known/openid-configuration" \
  --scope="openid email profile"

Adaptez l'utilisateur système, le chemin vers occ et le stockage du secret à votre installation. Pour relire la configuration d'un fournisseur sans afficher son secret en clair :

sudo -u www-data php occ user_oidc:provider entreprise --output=json_pretty

La commande crée le fournisseur si l'identifiant n'existe pas et si les paramètres nécessaires sont présents. Sur un fournisseur existant, elle modifie les options fournies. Évitez donc les scripts qui rejouent aveuglément une configuration incomplète.

Le navigateur part de Nextcloud, passe par le fournisseur d'identité et revient avec un code. Nextcloud échange ce code contre des jetons, contrôle le résultat puis associe l'identité au bon compte. Chaque étape doit être vérifiée séparément pendant la recette.

Quel claim choisir comme identifiant utilisateur ?

Le réglage User ID mapping détermine quel claim sert à retrouver l'utilisateur. user_oidc utilise sub par défaut. Dans OpenID Connect, la combinaison de l'émetteur iss et du sujet sub constitue l'identifiant stable prévu par le protocole pour l'utilisateur.

Un e-mail semble plus lisible, mais il peut changer lors d'un changement de nom, de domaine ou de filiale. Si l'e-mail sert d'identifiant et évolue, Nextcloud peut ne plus reconnaître le compte précédent. Le résultat peut être un nouveau compte, un espace vide ou une collision avec un compte existant.

L'option d'identifiant unique est activée par défaut. L'application combine le fournisseur et l'identité pour éviter que deux fournisseurs présentant la même valeur n'ouvrent le même compte Nextcloud. Ne la désactivez pas uniquement pour obtenir des identifiants plus lisibles. Une telle décision demande un inventaire des comptes existants, des fournisseurs et des conséquences sur les chemins utilisateurs.

Si LDAP fournit déjà les comptes, le mapping OIDC doit produire la même valeur que l'identifiant interne du backend LDAP et cette valeur doit être recherchable par sa requête de connexion. Sinon, l'authentification peut réussir côté IdP tout en échouant à rattacher le bon compte Nextcloud.

Quel mode de provisionnement choisir ?

Le provisionnement décide si user_oidc crée les comptes et met à jour leurs attributs. Les réglages système par défaut activent l'auto-provisionnement et le soft auto-provisioning.

Ces valeurs se placent dans la section user_oidc de config.php :

'user_oidc' => [
    'auto_provision' => true,
    'soft_auto_provision' => true,
    'disable_account_creation' => true,
],

Cet exemple convient à une organisation qui veut autoriser le SSO seulement pour des comptes préparés à l'avance. Ce n'est pas une valeur universelle. Une petite équipe peut préférer la création au premier accès, tandis qu'une entreprise reliée à LDAP peut exiger que l'annuaire reste la source de référence.

Pour que des collègues puissent partager des fichiers avec une personne avant sa première connexion, l'application expose aussi une API de pré-provisionnement. Réservez cette méthode à un flux administré, authentifié et journalisé. La présence d'une API ne remplace pas la définition du propriétaire des identités ni la procédure de suppression.

Comment mapper les claims et les groupes ?

Commencez avec le minimum nécessaire. L'application prévoit des mappings pour l'identifiant, le nom affiché, l'e-mail, le quota, la langue, la locale, l'avatar, le téléphone, l'organisation et plusieurs autres propriétés de profil. Demander et stocker chaque claim disponible augmente la dépendance au schéma de l'IdP sans améliorer automatiquement l'usage.

Une base raisonnable pour un pilote contient :

• sub pour l'identifiant ;
• name pour le nom affiché, si sa valeur est propre ;
• email pour l'adresse professionnelle ;
• groups uniquement si le fournisseur émet une liste maîtrisée et si la gestion des groupes est prévue.

Par défaut, l'application demande notamment les claims quota, name, email et groups, même lorsqu'aucun mapping personnalisé n'est renseigné. Le réglage enable_default_claims permet de désactiver ce comportement. Utilisez-le seulement après avoir déclaré explicitement les attributs attendus et testé les jetons réels.

Le provisionnement des groupes est désactivé par défaut. Lorsqu'il est activé, user_oidc peut créer les groupes absents à la connexion. L'application prend en charge une liste de noms séparés par des virgules, un tableau de chaînes ou un tableau d'objets comprenant un identifiant et un nom d'affichage.

La commande suivante illustre un fournisseur qui ne retient que les groupes commençant par nextcloud- et refuse les autres utilisateurs :

sudo -u www-data php occ user_oidc:provider entreprise \
  --mapping-groups="groups" \
  --group-provisioning=1 \
  --group-whitelist-regex='/^nextcloud-/' \
  --group-restrict-login-to-whitelist=1

Cette expression est un exemple construit. Adaptez-la aux valeurs exactes émises par votre IdP. Testez aussi la suppression d'un utilisateur du groupe autorisé, puis vérifiez la nouvelle connexion et les sessions déjà ouvertes selon la politique retenue.

Faut-il activer PKCE, la déconnexion unique et la redirection automatique ?

user_oidc active PKCE par défaut lorsque le fournisseur l'annonce compatible. PKCE lie le retour d'autorisation à une preuve créée au début du flux. Ne le désactivez que pour traiter une incompatibilité confirmée et documentée avec l'IdP.

La déconnexion unique est également activée par défaut. Si le document de découverte fournit un end_session_endpoint, Nextcloud peut demander la fin de la session côté fournisseur. L'application prend aussi en charge le backchannel logout, qui permet à l'IdP de notifier Nextcloud d'une fermeture de session. Cette fonction demande une URL dédiée côté fournisseur et une recette sur les différentes sessions du même utilisateur.

Avec un seul fournisseur configuré, il est possible de rediriger immédiatement la page de connexion vers l'IdP en désactivant les autres méthodes :

sudo -u www-data php occ config:app:set \
  --type=string --value=0 user_oidc allow_multiple_user_backends

Le paramètre ?direct=1 sur l'URL de connexion conserve l'accès au formulaire Nextcloud classique pour les administrateurs. Testez-le dans une fenêtre privée avec le compte de secours avant d'imposer la redirection. Conservez aussi la procédure hors de Nextcloud, puisque l'incident visé peut justement rendre la plateforme inaccessible.

Les options de validation Bearer concernent les appels API et WebDAV munis d'un jeton externe. Elles ne sont pas nécessaires au seul SSO dans le navigateur. N'activez check-bearer ou bearer-provisioning que si une intégration identifiée en a besoin, avec un périmètre de jeton et une stratégie de création de compte définis.

Quelle recette exécuter avant la mise en production ?

La première connexion réussie ne suffit pas. Préparez une matrice avec le résultat attendu pour chaque cas :

Testez les clients réellement utilisés. Les clients Nextcloud modernes ouvrent généralement un navigateur pour le flux de connexion. Un outil DAV ou une intégration qui ne sait pas suivre ce parcours peut demander un mot de passe d'application. Le guide des mots de passe d'application Nextcloud explique leur création et leur révocation par appareil.

Pendant le pilote, notez l'identifiant local créé, le backend associé, les groupes reçus et les changements observés après une nouvelle connexion. Gardez une copie de la configuration du fournisseur et un moyen de revenir au formulaire local. Une sauvegarde de la base et de la configuration reste nécessaire avant une modification d'identité importante, mais sa restauration ne doit pas être la première méthode de retour arrière pour un simple mapping incorrect.

Comment diagnostiquer un échec de connexion user_oidc ?

Procédez dans l'ordre du flux plutôt que de modifier plusieurs réglages à la fois :

1. Avant la redirection : vérifiez que l'application est active, que le fournisseur apparaît et que Nextcloud génère une URL publique correcte.
2. Chez le fournisseur : contrôlez le client ID, l'URI de redirection exacte, les scopes et la politique d'accès.
3. Au retour dans Nextcloud : recherchez une erreur de state, de code expiré ou d'échange au endpoint de jeton.
4. Pendant la validation : vérifiez l'émetteur, l'audience, la signature, les clés JWKS et l'heure des serveurs.
5. Pendant le rattachement : comparez le claim choisi, sa valeur réelle et les comptes déjà présents.
6. Pendant le provisionnement : contrôlez les claims de profil, les groupes, l'expression régulière et le mode de création.
7. Après la connexion : testez la session, la déconnexion, le client de synchronisation et la révocation.

Le cache JWKS propre au fournisseur reste valide une heure selon la documentation de l'application. Après une rotation de clés côté IdP, une mise à jour du fournisseur avec occ vide ce cache, même si aucune valeur fonctionnelle n'est modifiée. Ne désactivez pas les contrôles de signature ou de solidité des clés pour masquer un problème de rotation.

Si certains attributs n'apparaissent pas dans l'ID token mais sont disponibles sur l'endpoint userinfo, l'option enrich_login_id_token_with_userinfo peut les ajouter lors de la connexion. Elle est désactivée par défaut et ne s'applique pas au provisionnement pendant la validation d'un jeton Bearer. Activez-la seulement après avoir confirmé le contenu, la portée et la disponibilité de cet endpoint.

Conclusion

Une configuration user_oidc fiable repose sur quatre décisions : une URI de retour exacte, un identifiant stable, un mode de provisionnement explicite et des groupes limités au périmètre Nextcloud. Commencez avec un fournisseur, deux comptes pilotes et peu de mappings. Vérifiez ensuite les clients, la révocation, la déconnexion et l'accès de secours avant toute redirection automatique.

Étudier l'hébergement Nextcloud GaprodCompatibilité OIDC, mappings et applications à valider selon votre fournisseur d'identité

Sources officielles

• Manuel d'administration Nextcloud : OpenID Connect
• Nextcloud App Store : OpenID Connect user backend
• Dépôt officiel user_oidc, version 8.11.0
• README officiel de user_oidc 8.11.0
• Manifeste de compatibilité de user_oidc 8.11.0
• Commande officielle user_oidc:provider
• OpenID Connect Core 1.0, identifiant Subject
• Manuel utilisateur Nextcloud : mots de passe d'application