Tinyauth + Traefik : ajoutez un portail d’authentification à vos applications web

I. Présentation

Protégez vos services web avec Tinyauth : une solution open source légère, simple à déployer et idéale pour centraliser l’authentification dans votre Home Lab ou votre environnement Docker. Ce tutoriel explique comment installer et configurer Tinyauth en tant que middleware pour Traefik.

Dans un Home Lab, multiplier les services web rime souvent avec multiplier les écrans de connexion, enfin, quand ils existent. Pour ajouter une authentification centralisée à toutes les applications, vous pouvez opter pour des solutions comme Authentik ou Keycloak. Au-delà de ces deux applications très connues, il y a Tinyauth : une approche légère et épurée de l’authentification, pensée pour protéger facilement vos services derrière un reverse proxy (Traefik, Nginx Proxy Manager, Caddy).

Que ce soit dans un Home Lab, une petite infrastructure ou un environnement de dev, on peut rapidement se retrouver avec une multitude de services web : interfaces d’administration, outils internes, dashboards… C'est là que Tinyauth intervient. Couplé à Traefik, il permet d’unifier l’authentification sans mettre en place une usine à gaz. Tinyauth se place entre les utilisateurs et les conteneurs Docker pour afficher une page de login.

Pour authentifier les utilisateurs, Tinyauth peut s'appuyer sur une base de comptes locale, utiliser OAuth (sur Google ou GitHub, par exemple) et même s'interfacer avec un annuaire LDAP (LLDAP, OpenLDAP, Active Directory).

Note : l'intégration de Tinyauth avec vos services web Docker est basée sur le mécanisme de ForwardAuth de Traefik.

II. Principe de fonctionnement : Traefik + Tinyauth

Avant la partie pratique, clarifions le rôle de chacun des composants utilisés :

• Traefik : reverse proxy / load balancer qui reçoit les requêtes HTTP(S) et les route vers vos services (une boite à outils, un wiki, un site web, etc.).
• Tinyauth : service d’authentification et d’autorisation. Il reçoit les requêtes "à valider" de la part de Traefik en agissant comme un middleware, puis il authentifie l'utilisateur avant de répondre à Traefik.

Le lien entre Traefik et Tinyauth se fait grâce au mécanisme ForwardAuth :

1. Le client demande l'accès à un service web, par exemple : https://it-tools.it-connectlab.fr.
2. Traefik intercepte la requête et l’envoie d’abord à Tinyauth (ForwardAuth).
3. Tinyauth entre en action si l'utilisateur :
   • n’est pas connecté, renvoie une redirection vers une page de login ;
   • est connecté mais n’a pas les autorisations, renvoie une erreur (403 par exemple) ;
   • est connecté et autorisé, il renvoie un 2xx avec éventuellement des en-têtes HTTP spécifiques.
4. Traefik relaie alors la requête au service cible, en y ajoutant les en-têtes reçus.

Vos applications n’ont pas besoin de gérer elles-mêmes l’authentification, c’est Tinyauth qui s’en charge en proposant un portail d'authentification.

III. Installation de Tinyauth avec Docker

Point de départ de cette démonstration : un serveur Linux (Debian) sur lequel Docker est installé. Un conteneur avec le reverse proxy Traefik est déjà en cours d'exécution, tout comme un conteneur avec l'application IT-Tools. Cette application est accessible, sans authentification, à l'adresse suivante : https://it-tools.it-connectlab.fr. Si vous souhaitez utiliser ce point de départ, suivez mon guide d'introduction à Traefik.

L'objectif : protéger l'accès à IT-Tools en ajoutant une page de connexion gérée par Tinyauth.

A. Créer le dossier pour le projet

Nous allons commencer par créer un répertoire pour stocker les fichiers du projet Tinyauth :

mkdir /opt/docker-compose/tinyauth

B. Docker Compose Tinyauth

À l'intérieur du répertoire créé précédemment, nous allons créer un fichier docker-compose.yml. Voici le code à insérer dans ce fichier :

services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:v4
    container_name: tinyauth
    restart: unless-stopped
    networks:
      - frontend  
    environment:
      - APP_URL=https://tinyauth.it-connectlab.fr
      - USERS=${USERS}
      - SECRET=${SECRET}
      - LOG_LEVEL=debug
    labels:
      - traefik.enable=true
      - traefik.http.routers.tinyauth.rule=Host(`tinyauth.it-connectlab.fr`)
      - traefik.http.routers.tinyauth.entrypoints=web
      - traefik.http.routers.tinyauth-https.rule=Host(`tinyauth.it-connectlab.fr`)
      - traefik.http.routers.tinyauth-https.entrypoints=websecure
      - traefik.http.routers.tinyauth-https.tls=true
      - traefik.http.routers.tinyauth-https.tls.certresolver=ovhcloud
      - traefik.http.services.tinyauth.loadbalancer.server.port=3000
      - traefik.http.middlewares.tinyauth.forwardauth.address=http://tinyauth:3000/api/auth/traefik

networks:
  frontend:
    external: true

Cette configuration crée un conteneur nommé tinyauth, connecté au réseau Docker frontend sur lequel est déjà connecté Traefik. L'application Tinyauth sera accessible via l'adresse https://tinyauth.it-connectlab.fr (APP_URL), à laquelle deux routers Traefik sont associés (un en HTTP, l'autre en HTTPS). Un certificat TLS Let's Encrypt sera obtenu via le fournisseur de certificat ovhcloud, qui est configuré dans Traefik (c'est une interaction avec l'API OVHcloud pour gérer le challenge DNS du processus ACME).

J'attire votre attention sur deux variables d'environnement pour lesquelles les valeurs seront stockées dans un fichier distinct :

• USERS = sert à déclarer, de façon statique, un ou plusieurs utilisateurs.
• SECRET = sert à signer et chiffrer les sessions ou les jetons (cookies) générés par Tinyauth.

Enregistrez et fermez ce fichier.

Vous devez générer une valeur aléatoire pour la variable SECRET. En ligne de commande, vous pouvez le faire à l'aide d'OpenSSL comme ceci : openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32.

Pour créer un utilisateur statique, vous avez besoin de deux informations : un nom d'utilisateur et un mot de passe, ou plutôt le hash BCrypt d'un mot de passe. Vous pouvez utiliser un outil en ligne pour obtenir cette information ou en ligne de commande, avec la commande mkpasswd, par exemple.

apt install whois -y

mkpasswd --method=bcrypt
Password:
# Saisissez le mot de passe en mode interactif et copiez la valeur obtenue.

Voici un exemple de valeur obtenue (le point final fait partie de la valeur) : $2b$05$4K/ulQau1w1v/mR5UzwaOu8UQFAa/bT.DbnrbRK6ed0OFY.KucIQ.

Vous pouvez alors constituer une chaine sous cette forme : <nom utilisateur>:<hash bcrypt>. Dans l'exemple ci-dessous, le nom du compte sera adm_fb.

Créez un fichier nommé .env et ajoutez ce contenu :

USERS=<nom utilisateur>:<hash bcrypt>
SECRET=<la valeur obtenue avec la commande openssl>

# Par exemple :
USERS=adm_fb:$2b$05$4K/ulQau1w1v/mR5UzwaOu8UQFAa/bT.DbnrbRK6ed0OFY.KucIQ.
SECRET=2BBUv0YFcZRoWMndmG9kaI3US5QU7u6Z

J'ai eu des cas où il fallait doubler les $ dans la valeur du mot de passe pour que ça fonctionne. Ce qui donnerait :

$$2b$$05$$4K/ulQau1w1v/mR5UzwaOu8UQFAa/bT.DbnrbRK6ed0OFY.KucIQ.

Enregistrez et lancez la création du conteneur Docker TinyAuth :

cd /opt/docker-compose/tinyauth
docker compose up -d

IV. Protéger un service web avec Tinyauth

Pour ajouter une page d'authentification à un service web exécuté dans un conteneur Docker, vous devez éditer le fichier Docker Compose de l'application en question. Ici, nous prenons l'exemple du service IT-Tools, donc nous allons éditer le fichier /opt/docker-compose/it-tools/docker-compose.yml.

Dans la section dédiée aux labels Traefik, vous devez ajouter cette ligne pour lui associer le middleware Tinyauth :

        - traefik.http.routers.it-tools-https.middlewares=tinyauth

Ce qui donne cette configuration complète :

      labels:
        - traefik.enable=true
        - traefik.http.routers.it-tools.rule=Host(`it-tools.it-connectlab.fr`)
        - traefik.http.routers.it-tools.entrypoints=web
        - traefik.http.routers.it-tools-https.rule=Host(`it-tools.it-connectlab.fr`)
        - traefik.http.routers.it-tools-https.entrypoints=websecure
        - traefik.http.routers.it-tools-https.tls=true
        - traefik.http.routers.it-tools-https.tls.certresolver=ovhcloud
        - traefik.http.routers.it-tools-https.middlewares=tinyauth

Suite à cette modification, relancez le conteneur applicatif :

cd /opt/docker-compose/it-tools
docker compose down
docker compose up -d --build

Tentez d'accéder à l'application web, ici représentée par l'adresse : https://it-tools.it-connectlab.fr. Au lieu d'avoir l'interface d'IT-Tools, la page de connexion Tiny Auth s'affiche :

Donc, là, il n'y a plus le choix : il faut s'authentifier avec le compte renseigné dans le fichier .env.

Une fois l'authentification réussie, le reverse proxy Traefik nous redirige vers l'application IT-Tools. La configuration est opérationnelle !

V. Tinyauth et l'authentification OAuth

Plutôt que d'utiliser une base de comptes locale, nous allons utiliser la méthode OAuth couplée à GitHub. Ainsi, il sera possible de s'authentifier auprès du portail Tinyauth à l'aide d'un compte GitHub.

La première étape consiste à créer une nouvelle application OAuth sur GitHub (à partir de votre compte GitHub). Vous pouvez créer une application OAuth sur GitHub via la page github.com/settings/developers. Cliquez sur le bouton "New OAuth app".

Vous devez ensuite :

• Spécifier un nom pour l'application
• Définir la Homepage URL, c'est-à-dire l'adresse de votre Tinyauth.
• Spécifier la callback URL, en utilisant l'adresse de Tinyauth + /api/oauth/callback/github.

Voici un exemple :

Vous arrivez sur la page de votre application. Cliquez sur le bouton "Generate a new client secret" pour générer un secret permettant d'utiliser cette application. Copiez le "Client ID" et "Client secret" car nous allons en avoir besoin par la suite.

Éditez le fichier de configuration du conteneur Tinyauth :

nano /opt/docker-compose/tinyauth/docker-compose.yml

Puis, ajoutez ces trois variables d'environnement :

      - PROVIDERS_GITHUB_CLIENT_ID=${PROVIDERS_GITHUB_CLIENT_ID}
      - PROVIDERS_GITHUB_CLIENT_SECRET=${PROVIDERS_GITHUB_CLIENT_SECRET}
      - OAUTH_WHITELIST=${OAUTH_WHITELIST}

Quelques explications s'imposent :

• PROVIDERS_GITHUB_CLIENT_ID : la valeur Client ID obtenue précédemment.
• PROVIDERS_GITHUB_CLIENT_SECRET : la valeur Client secret obtenue précédemment.
• PROVIDERS_GITHUB_CLIENT_ID : la liste des adresses e-mail de comptes GitHub autorisés à se connecter. Sinon, n'importe qui avec un compte GitHub peut s'authentifier sur votre portail.

Puis, dans le fichier .env, configurez les variables d'environnement avec vos valeurs (ajoutez ces lignes à la suite de celles déjà présentes) :

PROVIDERS_GITHUB_CLIENT_ID=Ov23liQVitconnect
PROVIDERS_GITHUB_CLIENT_SECRET=e78bf94fb2ab4f16ditconnectitconnect
[email protected]

Enregistrez, puis relancez le conteneur Tinyauth :

cd /opt/docker-compose/tinyauth/
dodocker compose down
docker compose up -d --build

Désormais, quand nous tentons une connexion à l'application, un nouveau bouton apparaît sur la page de connexion Tinyauth ! Il permet de s'authentifier avec GitHub, ce qui est plutôt de bonne augure !

Il convient alors de préciser son nom d'utilisateur et son mot de passe.

Puis, d'autoriser l'application Tinyauth à obtenir l'adresse e-mail et les informations du profil (en lecture seule). Ces informations peuvent aussi être relayées à l'application sur laquelle une connexion est tentée.

Une fois l'authentification GitHub réussie, vous accédez à votre application !

VI. Personnaliser l'interface de Tinyauth

Tinyauth prend en charge plusieurs variables d'environnement que vous pouvez utiliser pour configurer votre instance, y compris pour personnaliser l'apparence. Vous pouvez notamment changer le titre et le fond d'écran. Voyons comment effectuer ces deux modifications.

Ouvrez le fichier /opt/docker-compose/tinyauth/docker-compose.yml. Dans la section environment, ajoutez la variable APP_TITLE avec la valeur souhaitée pour le titre visible au-dessus du formulaire. Par exemple :

      - APP_TITLE=IT-Connect Lab

Pour utiliser un fond d'écran personnalisé, vous avez deux options :

• Stocker l'image sur votre serveur et la monter dans le conteneur Tinyauth.
• Pointer vers l'image via une URL web, ce qui peut être une ressource externe hébergée sur un autre domaine.

Dans le cas où vous souhaitez stocker l'image sur votre serveur, vous devez positionner le fichier sous /opt/docker-compose/tinyauth/ puis le monter dans le conteneur via l'ajout d'une ligne sous volumes. Par exemple :

    volumes:
      - ./wallpaper.jpg:/data/resources/wallpaper.jpg:ro

Puis, dans la section environment, ajoutez deux lignes pour préciser le chemin vers le dossier disposant des ressources personnalisées (RESOURCES_DIR), puis le chemin vers le fichier image en lui-même (BACKGROUND_IMAGE). Voici un exemple (respectez bien ce format).

      - RESOURCES_DIR=/data/resources
      - BACKGROUND_IMAGE=/resources/wallpaper.jpg

Relancez le conteneur avec la nouvelle configuration :

docker compose down
docker compose up -d --build

VII. Le contrôle d'accès avec Tinyauth

Tinyauth intègre des fonctions pour le contrôle d'accès, notamment pour limiter l'accès à certains sous-domaines (ou certaines URL / chemins) uniquement à certains utilisateurs. Vous pouvez créer des règles basées sur les utilisateurs, les comptes OAuth, les chemins et les adresses IP (autoriser uniquement les connexions depuis une liste blanche d'adresses IP, par exemple).

Dans tous les cas, Tinyauth doit pouvoir surveiller vos conteneurs et lire les labels (comme le fait Traefik). Vous devez donc ajouter ce volume dans la configuration de Tinyauth :

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

La configuration s'effectue ensuite au niveau de chaque application, grâce à un système de labels Tinyauth. Vous devez rajouter une ligne pour préciser le nom de domaine de l'application (bien que ce soit facultatif car Tinyauth prend par défaut le sous-domaine) et ensuite ajouter les ACL Tinyauth.

L'exemple ci-dessous, positionné sur l'application IT-Tools, permet d'autoriser uniquement le compte adm_fb à accéder à cette application. Ici, on autorise explicitement un utilisateur (on peut aussi en préciser plusieurs), donc tous les autres seront interdits. Nous pouvons aussi faire l'inverse : tout autoriser et bloquer uniquement certains comptes, mais j'aime moins cette approche.

      labels:
        - traefik.enable=true
        - traefik.http.routers.it-tools.rule=Host(`it-tools.it-connectlab.fr`)
        - traefik.http.routers.it-tools.entrypoints=web
        - traefik.http.routers.it-tools-https.rule=Host(`it-tools.it-connectlab.fr`)
        - traefik.http.routers.it-tools-https.entrypoints=websecure
        - traefik.http.routers.it-tools-https.tls=true
        - traefik.http.routers.it-tools-https.tls.certresolver=ovhcloud
        - traefik.http.routers.it-tools-https.middlewares=tinyauth
        - tinyauth.apps.it-tools.config.domain=it-tools.it-connectlab.fr
        - tinyauth.apps.it-tools.users.allow=adm_fb

Relancez les deux conteneurs... Puis, testez. Pour l'occasion, j'ai ajouté un second utilisateur nommé flo et qui, en principe, doit se voir l'accès refusé. Voici le résultat obtenu :

D'autres exemples sont précisés dans la documentation officielle.

VIII. Docker Compose Tinyauth - Exemple complet

Pour finir, voici la configuration complète avec l'authentification GitHub et la personnalisation de l'interface Tinyauth :

services:
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth:v4
    container_name: tinyauth
    restart: unless-stopped
    networks:
      - frontend  
    environment:
      - APP_URL=https://tinyauth.it-connectlab.fr
      - APP_TITLE=IT-Connect Lab
      - RESOURCES_DIR=/data/resources
      - BACKGROUND_IMAGE=/resources/wallpaper.jpg
      - USERS=${USERS}
      - SECRET=${SECRET}
      - PROVIDERS_GITHUB_CLIENT_ID=${PROVIDERS_GITHUB_CLIENT_ID}
      - PROVIDERS_GITHUB_CLIENT_SECRET=${PROVIDERS_GITHUB_CLIENT_SECRET}
      - OAUTH_WHITELIST=${OAUTH_WHITELIST}
      - LOG_LEVEL=debug
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./wallpaper.jpg:/data/resources/wallpaper.jpg:ro
    labels:
      - traefik.enable=true
      - traefik.http.routers.tinyauth.rule=Host(`tinyauth.it-connectlab.fr`)
      - traefik.http.routers.tinyauth.entrypoints=web
      - traefik.http.routers.tinyauth-https.rule=Host(`tinyauth.it-connectlab.fr`)
      - traefik.http.routers.tinyauth-https.entrypoints=websecure
      - traefik.http.routers.tinyauth-https.tls=true
      - traefik.http.routers.tinyauth-https.tls.certresolver=ovhcloud
      - traefik.http.services.tinyauth.loadbalancer.server.port=3000
      - traefik.http.middlewares.tinyauth.forwardauth.address=http://tinyauth:3000/api/auth/traefik

networks:
  frontend:
    external: true    

Ainsi que le fichier .env associé :

USERS=adm_fb:$2b$05$4K/ulQau1w1v/mR5UzwaOu8UQFAa/bT.DbnrbRK6ed0OFY.KucIQ.
SECRET=2BBUv0YFcZRoWMndmG9kaI3US5QU7u6Z
PROVIDERS_GITHUB_CLIENT_ID=Ov23liQVitconnect
PROVIDERS_GITHUB_CLIENT_SECRET=e78bf94fb2ab4f16ditconnectitconnect
[email protected]

IX. Conclusion

À condition d'être un minimum à l'aise avec Docker, Tinyauth se présente comme une solution simple et efficace pour protéger n'importe quelle application par un portail d'authentification. L'association avec Traefik est très intéressante pour mettre en place une authentification centralisée.

Ce type d’architecture reste relativement simple à maintenir, tout en offrant un bon contrôle sur qui accède à quoi. Vous pouvez ensuite affiner les politiques d’accès, ajouter des groupes ou intégrer d’autres services, tout en conservant le même socle : Traefik en frontal, Tinyauth comme brique d’authentification partagée.

En complément de ce tutoriel, vous pouvez consulter la documentation de Tinyauth.

FAQ