IREX - Sécurisation de OpenWebUI avec Keycloak

1. Introduction

À l'heure où les modèles de langage (LLMs) transforment nos interactions avec la technologie, la sécurisation des plateformes qui les hébergent est devenue une priorité absolue. Sans une gestion robuste des accès, ces outils puissants peuvent devenir une porte d'entrée vers des vulnérabilités critiques.

OpenWebUI (anciennement Ollama WebUI) s'est rapidement imposé comme une interface utilisateur open-source de premier plan pour interagir avec des LLMs. Apprécié pour sa flexibilité et sa facilité d'utilisation, il permet de déployer rapidement un environnement de type "ChatGPT" en interne. Cependant, son système d'authentification natif, bien que fonctionnel, présente des limites dans un contexte d'entreprise : la gestion manuelle des utilisateurs est fastidieuse, peu évolutive et ne s'intègre pas à un annuaire d'entreprise existant.

C'est ici qu'intervient Keycloak. En tant que système de gestion d'identité et d'accès (IAM) open-source de référence, Keycloak offre une solution centralisée et puissante pour gérer l'authentification et les autorisations. En l'intégrant à OpenWebUI, nous pouvons bénéficier du Single Sign-On (SSO), d'une gestion fine des rôles et d'une sécurité de niveau entreprise.

Cet article vous guidera pas à pas dans le processus d'intégration de Keycloak avec OpenWebUI, en détaillant la configuration nécessaire sur chaque plateforme pour aboutir à une solution d'authentification unifiée et sécurisée.

2. Comprendre les composants : OpenWebUI et Keycloak

Présentation de Keycloak

Keycloak est bien plus qu'un simple gestionnaire de mots de passe. C'est une solution IAM complète qui permet de sécuriser des applications et des services avec un minimum de code. Ses fonctionnalités clés incluent :

• Single Sign-On (SSO) : Connectez-vous une seule fois pour accéder à plusieurs applications.
• Gestion centralisée des identités : Gérez vos utilisateurs, groupes et rôles depuis une seule interface d'administration.
• Support des standards : Il s'appuie sur des protocoles standards comme OpenID Connect (OIDC) et OAuth 2.0.
• Fédération d'identités : Intégrez des fournisseurs d'identité externes comme Google, GitHub, ou des annuaires d'entreprise (LDAP, Active Directory).

Présentation d'OpenWebUI

OpenWebUI est une interface web intuitive et réactive qui se connecte à des backends de modèles de langage comme Ollama ou des API compatibles OpenAI. Il démocratise l'accès aux LLMs en offrant une expérience utilisateur soignée, tout en étant entièrement auto-hébergé.

Vue d'ensemble de l'intégration

Le principe de l'intégration est simple : OpenWebUI ne gère plus lui-même les mots de passe. Il délègue entièrement cette responsabilité à Keycloak. Le flux d'authentification, basé sur le protocole OIDC, se déroule comme suit :

1. Un utilisateur non authentifié tente d'accéder à l'interface OpenWebUI.
2. OpenWebUI, voyant que l'utilisateur n'est pas connecté, le redirige automatiquement vers la page de connexion de Keycloak.
3. L'utilisateur saisit ses identifiants (email et mot de passe) sur la page sécurisée de Keycloak.
4. Après une authentification réussie, Keycloak redirige l'utilisateur vers OpenWebUI avec un jeton d'autorisation (JWT).
5. OpenWebUI valide ce jeton, récupère les informations de l'utilisateur (comme son nom et ses rôles) et lui accorde l'accès à l'interface.

3. Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Une instance de Keycloak fonctionnelle.
• Une instance d'OpenWebUI déployée.
• Un accès à un terminal en ligne de commande.
• Des connaissances de base sur le fonctionnement de Docker et la gestion des variables d'environnement.

4. Étape 1 : Configuration de Keycloak

La première étape consiste à préparer Keycloak pour qu'il reconnaisse OpenWebUI comme une application autorisée. Connectez-vous à la console d'administration de l'environnement Keycloak cible (par exemple, https://keycloak.dev.onesi.ca).

4.1 - Création du Client OIDC

Un "Client" est la représentation de notre service OpenWebUI au sein de Keycloak. Il définit les règles d'interaction entre les deux systèmes.

1. Assurez-vous d'avoir sélectionné le bon Realm (par exemple, IREX) dans le menu en haut à gauche.
2. Dans le menu principal, naviguez vers "Clients" et cliquez sur le bouton "Create client".
3. Remplissez les informations initiales du client :
   • Client type: OpenID Connect
   • Client ID: open-webui par exemple.
   • Name: OpenWebUI - DEV par exemple.
4. Sur l'écran suivant ("Capability config"), assurez-vous que l'interrupteur "Client authentication" est sur ON, puis sauvegardez.

4.2 - Configuration des URLs et du Secret

Une fois le client créé, il faut configurer ses points de communication et récupérer ses identifiants secrets.

1. Dans les paramètres du client, trouvez le champ "Valid Redirect URIs". C'est le paramètre de sécurité le plus important. Entrez l'URL de votre service OpenWebUI suivie de /* :

   https://open-webui.dev.onesi.ca/*

2. Remplissez également les champs "Root URL" et "Home URL" avec l'URL de base :

   https://open-webui.dev.onesi.ca

3. Cliquez sur "Save" en bas de la page.
4. Naviguez vers l'onglet "Credentials". Copiez le "Client secret" et conservez-le précieusement pour l'étape suivante.

4.3 - Création d'un Utilisateur de Test

Pour valider l'intégration, vous aurez besoin d'un compte utilisateur existant dans Keycloak.

1. Dans le menu principal du Realm, allez dans "Users" et cliquez sur "Add user".
2. Créez un utilisateur de test (par exemple, test.openwebui) en remplissant les champs requis.
3. Une fois l'utilisateur créé, allez dans son onglet "Credentials" pour lui définir un mot de passe permanent.

5. Étape 2 : Configuration d'OpenWebUI(via Ansible par exemple)

La configuration d'OpenWebUI pour l'intégration OIDC se fait en définissant des variables dans votre projet Ansible. L'automatisation se chargera de les passer au conteneur.

Modification du fichier de variables d'hôte

Ouvrez le fichier de variables correspondant à votre serveur par exemple,

inventory/dev/host_vars/open-webui.dev.onesi.ca.yml

et assurez-vous que les variables OIDC sont correctement renseignées.

            # --- Configuration de l'Intégration Keycloak OIDC ---
            enable_oauth_signup: "true"
            oauth_client_id: "open-webui"
            oauth_client_secret: "LE_SECRET_COPIE_DE_KEYCLOAK"
            
            # URL du "Discovery Document" de votre realm Keycloak
            openid_provider_url: "https://keycloak.dev.onesi.ca/auth/realms/IREX/.well-known/openid-configuration"
            
            # --- Configuration des Cookies, Rôles et Claims OIDC ---
            webui_url: "https://open-webui.dev.onesi.ca"
            webui_auth_cookie_secure: "true"
            webui_session_cookie_secure: "true"
            webui_auth_cookie_same_site: "None"
            webui_session_cookie_same_site: "None"
            oauth_email_claim: "email"
            oauth_username_claim: "preferred_username"
            default_user_role: "user"
        

Application de la configuration

Une fois les variables mises à jour, il suffit de relancer le playbook Ansible. L'automatisation se chargera de mettre à jour le fichier docker-compose.yml sur le serveur et de redémarrer les conteneurs avec la nouvelle configuration.

        ansible-playbook -i inventory/dev/ playbook.yml
    

Après l'exécution, le service sera prêt à utiliser l'authentification Keycloak.

6. Test et validation

Le Scénario de Connexion Utilisateur

Une fois le déploiement appliqué, suivez ces étapes pour valider le flux d'authentification complet :

1. Ouvrez une fenêtre de navigation privée (pour éviter tout conflit de cache) et accédez à l'URL de votre service. Par exemple : https://open-webui.dev.onesi.ca.
2. Sur la page d'accueil, vous devriez voir un bouton "Continue with SSO".
3. En cliquant dessus, vous serez redirigé vers la page de connexion officielle de Keycloak.
4. Connectez-vous avec un utilisateur existant dans votre Realm Keycloak (par exemple, le test.openwebui que vous avez créé).
5. Après une connexion réussie, Keycloak vous redirigera automatiquement vers l'interface principale d'OpenWebUI, et vous serez connecté !

Vérification Technique

Pour confirmer que l'intégration fonctionne en arrière-plan, vous pouvez inspecter les logs du conteneur OpenWebUI. Après une tentative de connexion réussie, vous devriez y voir des lignes confirmant la communication avec Keycloak et la création de l'utilisateur :

        # Commande à exécuter sur la VM
        sudo docker logs openwebui-dev
        
        # Extrait de log attendu
        INFO | httpx._client:... - HTTP Request: POST https://keycloak.../token "HTTP/1.1 200 OK"
        INFO | open_webui.models.auths:insert_new_auth - insert_new_auth
    

7. Aller plus loin

Gestion Fine des Rôles

La puissance de Keycloak réside dans sa capacité à gérer finement les accès. En créant des rôles spécifiques dans votre Realm (par exemple, admin-openwebui) et en les assignant à des utilisateurs, vous pouvez contrôler les permissions. Pour que OpenWebUI reconnaisse ces rôles, il est nécessaire de configurer un "Mapper" de type "User Realm Role" dans le "Client Scope" de votre application sur Keycloak.

Sécurisation du Trafic avec HTTPS

La communication entre le navigateur de l'utilisateur et le service est un point de sécurité critique. Dans notre architecture de déploiement (avec les scripts Bash ou Ansible), ce point est déjà pris en charge :

• Un conteneur Nginx est déployé en tant que reverse proxy.
• Il gère la terminaison SSL/TLS, ce qui signifie que tout le trafic externe est chiffré en HTTPS.
• Il redirige automatiquement tout le trafic non sécurisé (HTTP) vers HTTPS.

Cette configuration garantit que les identifiants et les jetons d'authentification qui transitent sur le réseau sont toujours protégés.

8. Conclusion

En intégrant Keycloak à OpenWebUI, vous avez transformé un service autonome en une application sécurisée et parfaitement intégrée à l'écosystème de l'entreprise. Vous bénéficiez désormais d'une sécurité renforcée, d'une gestion centralisée des identités et d'une expérience utilisateur simplifiée grâce au Single Sign-On (SSO).

Cette architecture "tout-en-conteneur" avec authentification déléguée est une pratique fondamentale pour les déploiements modernes. Elle garantit un environnement informatique robuste, sécurisé et facile à maintenir pour tous les services futurs.

9. Voir plus

Dans une pareille perspective, vous pouvez consulter :

• Déploiement de l'interface LibreChat avec Docker : guide pas à pas
• LibreChat : Une Alternative Libre et Performante à ChatGPT