Runbook: añadir PocketID OIDC a un servicio nuevo¶

Ubicación y alcance vigentes¶

El 22 de octubre de 2026, PocketID es CT213 en pmx51. La configuración activa consultada en ambos Caddy270/271 dirige este hostname a 192.168.0.XXX:1411, sin Sablier. No usar la antigua base de datos de VM208 como destino de administración. Resolver el propietario actual antes de operar.

Los ejemplos de aplicaciones siguientes son referencias históricas de integración, no un inventario de clientes ni confirmación de sus versiones o políticas actuales. Una nueva integración requiere el flujo de alta y una audiencia explícita; este runbook no autoriza crear clientes o ampliar grupos por sí solo.

Desde la LAN se pueden comprobar los dos DNS y el camino HTTPS por cada proxy. Estas consultas sólo leen discovery y claves públicas; no emiten tokens ni prueban la sesión de una aplicación. Primero confirmar que la ruta activa sigue siendo PocketID siempre encendido, sin middleware de activación bajo demanda.

# Esperado: NOERROR y A 192.168.0.XXX para ambos resolvers.
dig @192.168.0.XXX pocketid.monxas.casa A +noall +comments +answer
dig @192.168.0.XXX pocketid.monxas.casa A +noall +comments +answer

# Mantener SNI/Host y validar el certificado, fijando sólo el destino LAN.
# Requiere curl y jq. No seguir redirects ni desactivar TLS para obtener un PASS.
set -euo pipefail
for addr in 192.168.0.XXX 192.168.0.XXX 192.168.0.XXX; do
  curl --noproxy '*' --fail --silent --show-error \
    --connect-timeout 3 --max-time 8 \
    --resolve "pocketid.monxas.casa:443:$addr" \
    https://pocketid.monxas.casa/.well-known/openid-configuration |
    jq -e '.issuer == "https://pocketid.monxas.casa" and
           .jwks_uri == "https://pocketid.monxas.casa/.well-known/jwks.json"'
  curl --noproxy '*' --fail --silent --show-error \
    --connect-timeout 3 --max-time 8 \
    --resolve "pocketid.monxas.casa:443:$addr" \
    https://pocketid.monxas.casa/.well-known/jwks.json |
    jq -e '(.keys | type == "array") and (.keys | length > 0)'
done

El 22 de octubre a las18:19:54 CEST se contrastaron ambos DNS (26/13 ms) y las seis respuestas HTTP200, sin redirecciones y con validación TLS correcta. Discovery declara el issuer esperado y endpoints HTTPS del mismo origen; JWKS contiene una clave pública y se anuncia RS256. Esto acredita los caminos seleccionados, sin demostrar login, autorización, caída de nodo o conmutación VIP.

Cuándo usar OIDC nativo vs CF Access¶

Servicio tiene OIDC nativo	Mobile/desktop apps lo consumen	→
Sí (audiobookshelf, immich, paperless, etc.)	Sí	OIDC nativo (no CF Access — rompería las apps)
No	Sólo web admin	Proxy que autentique al usuario; CF Access + PocketID cubre la ruta WAN de Cloudflare, no el acceso directo por LAN
Sí	Sólo web	Tu elección — OIDC nativo es mejor (1 menos punto de fallo)

La protección WAN no acredita la protección LAN. Revalidar la capacidad OIDC de la versión instalada antes de elegir: por ejemplo, el Dozzle del homelab ya tiene OIDC nativo configurado. Una página HTTP200 o un endpoint llamado forward-auth no demuestra por sí solo validación de identidad.

Patrón general¶

Crear OIDC client en PocketID desde la administración de clientes
Configurar la app (env vars o admin UI)
Elegir grupos permitidos y verificar la identidad mediante el flujo admitido
Probar login

1. Crear OIDC client¶

Vía UI¶

Abrir PocketID → Administration → OIDC Clients → Add OIDC Client. Elegir el nombre, tipo de cliente y callbacks exactos según la aplicación. Guardar el secreto en SOPS o en el almacén privado existente; no imprimirlo en recibos o documentos.

Elegir explícitamente Allowed User Groups. Un cliente restringido sin grupos no permite usuarios. Seleccionar los grupos acordados; usar Unrestrict sólo cuando se haya decidido que todos los usuarios de PocketID pueden acceder. La documentación oficial de grupos y la guía de conexión describen esas opciones. No sustituir esta decisión por un trigger global.

El antiguo script de VM208 que insertaba clientes en SQLite y escribía secretos por stdout queda como antecedente histórico, no como procedimiento vigente. Para automatizar altas, preparar una integración con la API oficial y permisos acotados antes de ejecutarla; no escribir directamente en una base de producción.

2. Callback URLs por servicio (referencias históricas)¶

Servicio	Callback URL	Mobile callback (si aplica)
Vaultwarden	`https://<host>/identity/connect/oidc-signin`	—
Karakeep	`https://<host>/api/auth/callback/custom`	—
Audiobookshelf	`https://<host>/auth/openid/callback`	`audiobookshelf://oauth`
Immich	`https://<host>/auth/login`	`app.immich:///oauth-callback`
Paperless-ngx	`https://<host>/accounts/oidc/<provider_id>/login/callback/`	—
Jellyseerr	`https://<host>/api/v1/auth/oidc-callback`	—
Grafana	`https://<host>/login/generic_oauth`	—
Stirling-PDF	`https://<host>/login/oauth2/code/<provider>`	—

3. Config por tipo de app¶

Tipo A — env vars en compose¶

Vaultwarden (ojo: requiere fork timshel/oidcwarden)¶

image: timshel/oidcwarden:latest    # mainline NO incluye SSO
environment:
  - SSO_ENABLED=true
  - SSO_ONLY=false
  - SSO_AUTHORITY=https://pocketid.monxas.casa
  - SSO_CLIENT_ID=${VW_OIDC_ID}
  - SSO_CLIENT_SECRET=${VW_OIDC_SECRET}
  - SSO_PKCE=true
  - SSO_SCOPES=openid profile email
  - SSO_FRONTEND=override          # importante para que el botón aparezca
  - SSO_CALLBACK_PATH=/identity/connect/oidc-signin

Karakeep¶

environment:
  - NEXTAUTH_URL=https://<host>     # debe ser el público, NO LAN
  - OAUTH_WELLKNOWN_URL=https://pocketid.monxas.casa/.well-known/openid-configuration
  - OAUTH_CLIENT_ID=${KK_OIDC_ID}
  - OAUTH_CLIENT_SECRET=${KK_OIDC_SECRET}
  - OAUTH_PROVIDER_NAME=PocketID
  - OAUTH_SCOPE=openid profile email
  - OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING=true

Paperless-ngx (ojo: requiere PAPERLESS_APPS extra)¶

environment:
  - PAPERLESS_URL=https://<host>
  - PAPERLESS_APPS=allauth.socialaccount.providers.openid_connect   # CRÍTICO
  - PAPERLESS_SOCIALACCOUNT_PROVIDERS={"openid_connect":{"APPS":[{"provider_id":"pocketid","name":"PocketID","client_id":"${PAP_OIDC_ID}","secret":"${PAP_OIDC_SECRET}","settings":{"server_url":"https://pocketid.monxas.casa/.well-known/openid-configuration"}}],"OAUTH_PKCE_ENABLED":true}}
  - PAPERLESS_SOCIAL_AUTO_SIGNUP=True
  - PAPERLESS_ACCOUNT_DEFAULT_HTTP_PROTOCOL=https

Tipo B — admin UI¶

Audiobookshelf (Settings → Auth → OpenID Connect)¶

Issuer URL: https://pocketid.monxas.casa
Authorization URL: https://pocketid.monxas.casa/authorize
Token URL: https://pocketid.monxas.casa/api/oidc/token
Userinfo URL: https://pocketid.monxas.casa/api/oidc/userinfo
JWKS URL: https://pocketid.monxas.casa/.well-known/jwks.json
Logout URL: https://pocketid.monxas.casa/api/oidc/end-session
Match by: email
Auto-register: ✅
Subfolder for Redirect URLs: VACIO (si no, mete /audiobookshelf en la callback)

Immich (Administration → Authentication → OAuth)¶

Issuer URL: https://pocketid.monxas.casa/.well-known/openid-configuration
Scope: openid email profile
Signing alg: RS256
Storage label claim: preferred_username
Auto register: ✅

OIDC Domain: pocketid.monxas.casa (sin https)
Allow new users: ✅
Email match required: ✅

4. Identidad y restricciones¶

Si aparece «You're not allowed to access this service», revisar el cliente y sus grupos permitidos. No eliminar la restricción para ocultar el error. Si una app requiere correo verificado, resolver la verificación de identidad por el flujo admitido; no marcar todos los usuarios como verificados mediante SQL.

Las instrucciones antiguas de este archivo incluían triggers SQLite que ampliaban clientes y verificaban usuarios automáticamente. Se conservan en el historial Git, pero no deben reaplicarse como parte de un alta. Esta corrección documental no inspecciona ni modifica los triggers, clientes o permisos existentes.

5. Prueba de autenticación¶

La prueba sin login de la entrada no acredita una sesión. Para la prueba funcional, acordar antes la identidad y audiencia esperadas y confirmar si la ruta de la app activa un servicio bajo demanda. Abrir la aplicación en el navegador, seleccionar Login with PocketID, autenticar con passkey y comprobar el retorno autenticado y los permisos esperados. Registrar por separado lo que se haya probado; no dar por válido el login sólo porque la página o una redirección devuelvan HTTP200/302.

6. Retirar una integración¶

Antes de borrar un cliente, identificar sus consumidores y confirmar su retirada. Usar la administración de PocketID o una operación API específica; no ejecutar DELETE SQL contra rutas heredadas de VM208. Retirar después la configuración de la aplicación mediante su fuente mantenida, preservando los demás clientes.

7. Reference¶

Doc OIDC + CF Access: ../security/cloudflare-access-pocketid.md
Endpoints PocketID: https://pocketid.monxas.casa/.well-known/openid-configuration
Propietario observado, 22 octubre: CT213 en pmx51; revalidar ubicación antes de administrar.