Pocket ID: proveedor OIDC ligero en un solo contenedor

Por qué autoalojar tu proveedor OIDC

Lo que obtienes con un IdP OIDC autoalojado

• Identidad centralizada — una sola cuenta para Gitea, Nextcloud, Grafana y todos los servicios compatibles con OIDC.
• Revocación global — deshabilitar una cuenta en Pocket ID corta el acceso a todas las aplicaciones conectadas en la siguiente renovación del token.
• Autenticación por passkeys — Touch ID, Face ID o una clave FIDO2 como único factor, sin contraseña que transmitir.
• Sin dependencia en la nube — tus identidades permanecen bajo tu jurisdicción, sin cuotas de usuarios ni precios por acción.
• Huella mínima — Pocket ID consume menos de 50 MB de RAM en reposo, frente a 300–600 MB de Authentik y 1–2 GB de Keycloak.
• SQLite integrado — no hay motor de base de datos externo que aprovisionar ni respaldar por separado.
• Back-channel logout (v2.18.0) — cuando se deshabilita un usuario o revoca un cliente, Pocket ID notifica a las aplicaciones registradas e invalida sus sesiones en el lado del servidor.
• Contenedor único — el servicio completo cabe en una imagen Docker de ~30 MB, sin dependencia de Redis ni worker separado.

Requisitos concretos

Instalación de Pocket ID

1. 01

   Preparar el VPS y el dominio

   Contrata un VPS con Ubuntu 22.04 o Debian 12 con al menos 512 MB de RAM. Crea un registro DNS de tipo A apuntando auth.example.com a la IP de tu VPS.

   Instala Docker y el plugin Compose:

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

2. 02

   Crear el directorio de trabajo

   En el servidor, crea un directorio dedicado:

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

3. 03

   Escribir el fichero docker-compose.yml

   Crea /opt/pocket-id/docker-compose.yml:

   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.example.com"
         TRUST_PROXY: "true"

4. 04

   Configurar el proxy inverso nginx

   Crea el vhost nginx para auth.example.com:

   server {
       listen 443 ssl http2;
       server_name auth.example.com;
   
       ssl_certificate     /etc/letsencrypt/live/auth.example.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;
   
       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;
       }
   }

   Obtén el certificado con Certbot:

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

5. 05

   Iniciar el contenedor

   Desde /opt/pocket-id:

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

   La línea de log Starting Pocket ID on :1411 confirma que el servidor está listo.

6. 06

   Crear la cuenta de administrador y registrar un passkey

   En la primera visita, Pocket ID solicita crear la cuenta de administrador. Introduce tu correo electrónico y registra inmediatamente un passkey: ve a Configuración → Passkeys → Añadir y sigue las indicaciones del navegador.

7. 07

   Registrar tu primera aplicación OIDC

   En la interfaz de administración, abre Clientes OIDC → Nuevo cliente. Rellena el nombre y la URL de callback. Pocket ID v2.18.0 crea automáticamente un client_secret — guárdalo inmediatamente.

8. 08

   Probar el flujo desde la aplicación cliente

   En Gitea, ve a Administración → Fuentes de autenticación → Añadir → OAuth2. Selecciona OpenID Connect, introduce el Client ID, el Client Secret y la URL de descubrimiento https://auth.example.com/.well-known/openid-configuration. Lanza un inicio de sesión de prueba para verificar el flujo completo.

Configuración post-instalación

Solución de problemas

Errores comunes y soluciones

• 502 Bad Gateway en todas las páginas — causa más frecuente: los buffers de nginx son demasiado pequeños para las cabeceras de respuesta OIDC de Pocket ID. Añade proxy_buffer_size 256k, proxy_buffers 4 512k y proxy_busy_buffers_size 512k en tu bloque location / y recarga nginx.
• redirect_uri_mismatch durante el inicio de sesión — la Callback URL declarada en Pocket ID no coincide exactamente con la enviada por la aplicación cliente. Verifica la barra diagonal final, el esquema http vs https y el número de puerto.
• invalid_client al intercambiar el código — el client_secret enviado por la aplicación no coincide. En v2.18.0, Pocket ID crea un secreto automáticamente; si no lo guardaste, regénéralo desde el registro del cliente.
• Passkey rechazado: NotAllowedError — el navegador no puede acceder a las APIs de WebAuthn sin HTTPS. Verifica que APP_URL esté configurado como https://... y que el certificado TLS sea válido.
• Las sesiones no se invalidan tras la revocación — el back-channel logout requiere que la aplicación cliente declare una Backchannel Logout URL. Sin esta URL, Pocket ID no puede notificar a la aplicación; las sesiones existentes expirarán a su duración natural.

Pocket ID, Authentik, Keycloak, Authelia: cuál elegir

Desplace la tabla

Conclusión