Comment configurer Keycloak comme fournisseur d'identité pour ownCloud Infinite Scale

Ce guide explique comment connecter ownCloud Infinite Scale (oCIS) à Keycloak via OpenID Connect (OIDC), la couche d'identité basée sur OAuth 2.0. Keycloak authentifie les utilisateurs ; oCIS fait confiance à l'identité signée et aux informations d'accès fournies par Keycloak. La connexion via navigateur utilise des redirections HTTPS, et oCIS doit également accéder aux points de terminaison de découverte et de signature de clés de Keycloak.

Au 6 octobre 2026, la documentation d'administration d'ownCloud décrit ces paramètres sous Infinite Scale 9.0. L'exemple de déploiement officiel de Keycloak constitue un point de départ utile, mais son fichier Compose et son exportation de domaine peuvent évoluer. Privilégiez les versions d'image compatibles et vérifiez les fichiers que vous déployez plutôt que de copier aveuglément un exemple non versionné.

Ce dont vous avez besoin avant de configurer OIDC

Configurez l'adresse HTTPS publique d'oCIS (par exemple https://cloud.example.com, oCIS.com) et celle de Keycloak (par exemple, Keycloak.com https://sso.example.com). Ces deux adresses doivent être correctement résolues par les navigateurs des utilisateurs. Le serveur oCIS doit également pouvoir accéder aux métadonnées OIDC et aux clés de signature publiques de Keycloak. Si un proxy inverse est utilisé pour l'un ou l'autre service, configurez son nom d'hôte public et ses en-têtes de transfert de manière cohérente.

• Un déploiement ownCloud Infinite Scale fonctionnel et un accès administrateur à son environnement ou à sa configuration Compose.
• Un domaine Keycloak fonctionnel et un accès administrateur sont requis. Un domaine est un espace de noms Keycloak pour les utilisateurs, les clients, les rôles et les paramètres d'identité.
• Un certificat TLS approuvé par le navigateur et par le serveur qui valide le certificat TLS de Keycloak. En production, la vérification du certificat ne doit pas être désactivée.
• Une décision concernant la correspondance des comptes : connecter les utilisateurs oCIS existants à des revendications d’identité stables, ou activer la création de comptes lors de la première connexion avec le backend utilisateur requis autorisant l’écriture.

1. Trouvez l'émetteur exact de Keycloak

Dans Keycloak, l'émetteur OIDC correspond généralement à l'URL du domaine, et non à l'URL de la console d'administration ni à celle du document de découverte. Pour un domaine nommé `<domain>` team, cela peut ressembler à `<domain>` https://sso.example.com/realms/team. Les installations plus anciennes ou les déploiements avec un préfixe de chemin peuvent différer ; par conséquent, ne reconstituez pas cette valeur de mémoire. Ouvrez le document de découverte du domaine à l'adresse `<domain>` https://sso.example.com/realms/team/.well-known/openid-configurationet copiez exactement la valeur de sa issuerpropriété `OIDC`.

Depuis un serveur pouvant accéder à Keycloak, vous pouvez examiner le document avec :

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

Vérifiez que l'émetteur renvoyé utilise le même schéma, le même hôte, le même chemin et le même nom de domaine que ceux configurés dans oCIS. OpenID Connect valide l'identité de l'émetteur avec précision ; une erreur de nom d'hôte du proxy inverse ou une barre oblique supplémentaire peut empêcher la connexion.

2. Enregistrez un client OIDC pour ownCloud Web

Un client est l'application enregistrée que Keycloak utilise pour déterminer quel service peut demander une connexion. Créez ou adaptez un client OpenID Connect dans le domaine utilisé par oCIS. Utilisez un ID client tel que `<client_id>` web, ou une valeur personnalisée, et assurez-vous qu'il corresponde à la WEB_OIDC_CLIENT_IDvaleur dans oCIS. L'exemple officiel ownCloud utilise `<client_id>` webcomme valeur par défaut.

Pour un client basé sur un navigateur, utilisez le flux de code d'autorisation standard et une configuration de client public conforme au domaine d'exemple officiel. Indiquez précisément les modèles de redirection HTTPS et de redirection post-déconnexion requis par votre déploiement. Un modèle de nom d'hôte précis, tel que ` https://cloud.example.com/*example.com`, est plus facile à auditer qu'un modèle générique générique applicable à tous les hôtes. Ajoutez uniquement les origines web nécessaires à votre déploiement. Ne créez pas de secret client pour un client navigateur public et ne l'intégrez pas ensuite à la configuration frontale.

3. Vérifier les revendications et les portées

Les revendications OIDC sont des attributs d'identité contenus dans un jeton ou renvoyés par le point de terminaison user-info. Choisissez avec soin la revendication « nom d'utilisateur ». Le proxy ownCloud utilise par défaut cette preferred_usernamerevendication pour la résolution d'un utilisateur, et l'exemple Keycloak configure le client web avec les étendues de profil et d'adresse e-mail standard. Vérifiez que votre domaine renvoie bien les revendications que vous utilisez ; leur disponibilité dépend des étendues client et des mappeurs de protocole.

Pour les comptes existants, la revendication configurée doit correspondre à l'attribut utilisateur ownCloud stable correspondant. Un nom d'utilisateur ou une adresse e-mail modifiés peuvent entraîner des problèmes d'association de compte si vous les utilisez comme identifiant permanent. La subrevendication est garantie unique et stable par fournisseur d'identité, mais elle peut ne pas correspondre à un nom d'utilisateur préexistant. Testez l'association de compte avec un compte non administrateur avant d'ouvrir l'accès à tous les utilisateurs.

4. Pointez l'échelle infinie vers Keycloak

Configurez les valeurs suivantes dans l'environnement pour le déploiement oCIS. Cet exemple suppose l'utilisation du protocole HTTPS et d'un domaine Keycloak /realms/team. Utilisez vos propres URL. Ce bloc de style YAML est donné à titre d'illustration ; Docker Compose, Kubernetes, systemd et d'autres méthodes de déploiement expriment les variables d'environnement différemment.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERSélectionne le fournisseur d'identité externe. PROXY_OIDC_REWRITE_WELLKNOWN=trueConfigure le proxy pour qu'il réécrive le point de terminaison de découverte OpenID Connect vers l'émetteur configuré ; ownCloud indique que cette opération est nécessaire pour que ses clients de bureau et mobiles puissent détecter le fournisseur. WEB_OIDC_CLIENT_IDDoit correspondre au client Keycloak. L'exclusion idpsuit l'exemple Keycloak d'ownCloud afin que le fournisseur intégré ne soit pas démarré comme fournisseur de connexion actif.

Pour qu'oCIS crée des comptes dès la première connexion réussie, PROXY_AUTOPROVISION_ACCOUNTS=trueconfigurez le service Graph avec un backend utilisateur autorisant l'écriture. Attribuez PROXY_USER_OIDC_CLAIMla PROXY_AUTOPROVISION_CLAIM_USERNAMEmême revendication ; pour l'attribut « nom d'utilisateur », consultez la documentation ownCloud PROXY_USER_CS3_CLAIM=usernamerelative à ce processus. L'approvisionnement automatique est optionnel et doit être testé indépendamment de l'authentification. Ne l'activez que si les revendications entrantes sont uniques et correctement mappées.

5. Autoriser le fournisseur d'identité dans la politique de sécurité du contenu

Infinite Scale utilise une politique de sécurité du contenu (CSP) pour contrôler les origines externes que son client web peut contacter. La documentation d'ownCloud indique qu'un fournisseur d'identité externe tel que Keycloak requiert une définition CSP appropriée. Si le bouton de connexion s'affiche mais que le navigateur bloque la requête, vérifiez la console du navigateur pour détecter d'éventuelles erreurs CSP. Configurez la politique PROXY_CSP_CONFIG_FILE_LOCATIONet autorisez uniquement l'origine Keycloak et les directives nécessaires à votre déploiement. Redémarrez le proxy ou le déploiement après avoir modifié le fichier. N'autorisez pas toutes les origines pour résoudre un problème de connexion.

6. Redémarrez et vérifiez le flux complet

Appliquez les modifications d'environnement et redémarrez le déploiement oCIS en utilisant la méthode que vous utilisez habituellement pour le gérer. Il n'existe pas de commande de redémarrage universelle : les contrôles diffèrent selon qu'il s'agisse d'un projet Compose, d'une charge de travail Kubernetes ou d'un service systemd. Vérifiez ensuite chaque maillon de la chaîne :

1. Ouvrez l'URL de découverte Keycloak et vérifiez qu'elle renvoie un JSON avec un issuer, authorization_endpoint, token_endpoint, et jwks_uri.
2. Ouvrez l'URL web d'ownCloud dans une fenêtre de navigation privée. Vérifiez que le navigateur est bien redirigé vers le domaine Keycloak attendu.
3. Connectez-vous avec un compte de test et vérifiez que le navigateur renvoie bien au même nom d'hôte ownCloud sans boucle de redirection.
4. Vérifiez que l'utilisateur prévu (et non un doublon nouvellement créé) apparaît bien dans Infinite Scale et qu'il a accès uniquement aux ressources attendues.
5. Testez la déconnexion, puis répétez l'opération avec un deuxième compte. Si des clients de bureau ou mobiles sont concernés, testez leur détection et leur connexion séparément.

Les défaillances courantes et leur signification habituelle

Liste de contrôle de production

• Nous avons testé les versions ownCloud et Keycloak avec des épingles plutôt que de nous fier à une latestétiquette flottante.
• Utilisez HTTPS pour les deux services publics et conservez la vérification des certificats. ownCloud indique que le remplacement du protocole TLS par une méthode non sécurisée est inadapté à la production.
• Protégez les identifiants d'administrateur Keycloak, sauvegardez la base de données Keycloak et la configuration du domaine, et limitez l'accès à l'administration Keycloak.
• Limitez les URI de redirection et les origines Web aux noms d'hôte réels d'ownCloud.
• Documentez la revendication d'identifiant choisie et les conséquences de la modification des noms d'utilisateur, des noms de domaine, des URL de l'émetteur ou des identifiants client.
• Testez l'accès de récupération avant de basculer une instance de production et conservez une procédure de restauration planifiée de la configuration précédente.

Références officielles

• Configuration du service proxy ownCloud Infinite Scale 9.0
• Guide d'exemple de déploiement Keycloak sur ownCloud
• Fichiers de déploiement officiels ownCloud ocis_keycloak
• Guide d'administration du serveur Keycloak 26.8
• Aspects de sécurité d'ownCloud Infinite Scale