Pocket ID : fournisseur OIDC léger en un conteneur

Pourquoi auto-héberger son fournisseur OIDC

Ce que vous obtenez avec un IdP OIDC self-hosted

• Identité centralisée — un seul compte pour Gitea, Nextcloud, Grafana et tous les services compatibles OIDC.
• Révocation globale — désactiver un compte dans Pocket ID coupe l'accès à toutes les applications connectées au prochain renouvellement de token.
• Authentification par passkeys — Touch ID, Face ID ou clé FIDO2 comme seul facteur, sans mot de passe à faire circuler.
• Aucune dépendance cloud — vos identités restent sous votre juridiction, sans quota d'utilisateurs ni tarification à l'acte.
• Empreinte minimale — Pocket ID consomme moins de 50 Mo de RAM au repos, contre 300 à 600 Mo pour Authentik et 1 à 2 Go pour Keycloak.
• SQLite embarqué — aucun moteur de base de données externe à provisionner ou à sauvegarder séparément.
• Back-channel logout (v2.18.0) — lorsqu'un utilisateur est désactivé ou révoque un client, Pocket ID notifie les applications enregistrées et invalide leurs sessions côté serveur.
• Un seul conteneur — l'ensemble du service tient dans une image Docker de 30 Mo environ, sans dépendance Redis, sans worker séparé.

Prérequis chiffrés

Installation de Pocket ID

1. 01

   Préparer le VPS et le domaine

   Commandez un VPS avec Ubuntu 22.04 ou Debian 12 et au moins 512 Mo de RAM. Créez un enregistrement DNS de type A pointant auth.votre-domaine.com vers l'IP de votre VPS. Ce sous-domaine est l'URL publique de votre instance Pocket ID — elle doit être joignable avant la première configuration, car les redirections OIDC s'y appuient.

   Installez Docker et le plugin Compose :

   curl -fsSL https://get.docker.com | sh

2. 02

   Créer le répertoire de travail

   Sur le serveur, créez un répertoire dédié et placez-y le fichier Compose :

   mkdir -p /opt/pocket-id && cd /opt/pocket-id

3. 03

   Écrire le fichier docker-compose.yml

   Créez /opt/pocket-id/docker-compose.yml avec le contenu suivant :

   services:
     pocket-id:
       image: ghcr.io/pocket-id/pocket-id:v2.18.0
       container_name: pocket-id
       restart: unless-stopped
       ports:
         - "1411:1411"
       volumes:
         - ./data:/app/data
       environment:
         APP_URL: "https://auth.votre-domaine.com"
         TRUST_PROXY: "true"

   La variable APP_URL doit correspondre exactement à l'URL publique de votre instance, schéma HTTPS compris. TRUST_PROXY: "true" indique à Pocket ID de faire confiance aux en-têtes X-Forwarded-* transmis par le reverse proxy.

4. 04

   Configurer le reverse proxy nginx

   Créez le vhost nginx pour auth.votre-domaine.com. Pocket ID écoute en HTTP sur le port 1411 ; le reverse proxy se charge de TLS.

   server {
       listen 443 ssl http2;
       server_name auth.votre-domaine.com;
   
       ssl_certificate     /etc/letsencrypt/live/auth.votre-domaine.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/auth.votre-domaine.com/privkey.pem;
   
       # Augmenter les buffers pour les en-têtes OIDC
       proxy_buffer_size   256k;
       proxy_buffers       4 512k;
       proxy_busy_buffers_size 512k;
   
       location / {
           proxy_pass         http://127.0.0.1:1411;
           proxy_set_header   Host              $host;
           proxy_set_header   X-Real-IP         $remote_addr;
           proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
           proxy_set_header   X-Forwarded-Proto $scheme;
       }
   }

   Procurez le certificat avec Certbot avant de recharger nginx :

   certbot certonly --nginx -d auth.votre-domaine.com
   nginx -t && systemctl reload nginx

   Note sur les buffers : Pocket ID produit des en-têtes de réponse plus grands que la valeur nginx par défaut. Sans les directives proxy_buffer_size et proxy_buffers, les pages peuvent répondre avec une erreur 502 silencieuse.

5. 05

   Démarrer le conteneur

   Depuis /opt/pocket-id :

   docker compose up -d
   docker compose logs -f pocket-id

   La ligne de log Starting Pocket ID on :1411 confirme que le serveur est prêt. Accédez à https://auth.votre-domaine.com pour terminer la configuration initiale.

6. 06

   Créer le compte administrateur et enregistrer un passkey

   À la première visite, Pocket ID propose de créer le compte administrateur. Renseignez votre e-mail, puis enregistrez immédiatement un passkey : cliquez sur Paramètres → Passkeys → Ajouter et suivez l'invite de votre navigateur (Touch ID, Windows Hello ou clé FIDO2). Une fois le passkey enregistré, c'est le seul facteur requis pour les connexions suivantes.

7. 07

   Déclarer votre première application OIDC

   Dans l'interface d'administration, ouvrez OIDC Clients → Nouveau client. Renseignez :
   - Nom : l'identifiant lisible de l'application (ex. Gitea)
   - Callback URL : l'URL de redirection déclarée dans l'application cliente (ex. https://git.votre-domaine.com/user/oauth2/pocket-id/callback)

   Pocket ID v2.18.0 crée automatiquement un client_secret à la création — récupérez-le immédiatement, il ne sera plus affiché en clair par la suite.

   Notez le Client ID et l'URL de découverte https://auth.votre-domaine.com/.well-known/openid-configuration : ce sont les deux valeurs à saisir dans l'application cliente.

8. 08

   Tester le flux depuis l'application cliente

   Dans Gitea, allez dans Administration → Sources d'authentification → Ajouter → OAuth2. Sélectionnez le fournisseur OpenID Connect, renseignez le Client ID, le Client Secret et l'URL de découverte. Déclenchez une connexion de test : le navigateur doit être redirigé vers auth.votre-domaine.com, vous proposer le passkey enregistré, puis vous renvoyer vers Gitea en étant connecté.

Configuration post-installation

Dépannage

Erreurs courantes et solutions

• 502 Bad Gateway sur toutes les pages — cause la plus fréquente : les buffers nginx sont trop petits pour les en-têtes de réponse OIDC de Pocket ID. Ajoutez proxy_buffer_size 256k, proxy_buffers 4 512k et proxy_busy_buffers_size 512k dans votre bloc location / et rechargez nginx.
• redirect_uri_mismatch lors du login — la Callback URL déclarée dans Pocket ID ne correspond pas exactement à celle envoyée par l'application cliente. Vérifiez la présence ou l'absence d'un slash final, le schéma http vs https et le port. La correspondance doit être exacte, caractère pour caractère.
• invalid_client au moment de l'échange du code — le client_secret envoyé par l'application ne correspond pas. En v2.18.0, Pocket ID crée un secret automatiquement à la création du client ; si vous n'avez pas noté ce secret, régénérez-en un depuis la fiche client dans l'administration.
• Passkey refusé : NotAllowedError — votre navigateur ne peut pas accéder aux API WebAuthn sans HTTPS. Vérifiez que APP_URL est bien en https://... et que le certificat TLS est valide (ni auto-signé, ni expiré) ; Certbot doit avoir émis un certificat pour le bon domaine.
• Les sessions ne sont pas invalidées après révocation — le back-channel logout nécessite que l'application cliente déclare une Backchannel Logout URL dans sa fiche OIDC. Sans cette URL, Pocket ID ne peut pas notifier l'application ; les sessions existantes expireront à leur durée naturelle. Vérifiez que le champ est renseigné et joignable depuis le conteneur Pocket ID.

Pocket ID, Authentik, Keycloak, Authelia : que choisir

Faites défiler le tableau

Conclusion