Lightweight Homelab Identity: Deploying Pocket-ID for OIDC Single Sign-On

Enterprise identity providers like Keycloak and Authentik offer extensive feature sets, but their multi-gigabyte RAM footprints, heavy Java/Python runtimes, and complex administrative models represent massive overkill for self-hosted homelabs and small VPS instances.

Pocket-ID is a modern, ultra-lightweight OpenID Connect (OIDC) provider written in Go. Consuming under 50MB of RAM, it features native Passkey/WebAuthn authentication, a distroless container image, read-only root filesystem support, and standardized OIDC discovery (.well-known/openid-configuration), allowing seamless single sign-on across all your self-hosted apps.

⚡ Quick Runbook: 60-Second Implementation

TL;DR: Deploy a hardened Pocket-ID instance with Docker secrets and memory limits:

# compose.yaml
services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v2.19.1-distroless
    container_name: pocket-id
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    user: "1000:1000"
    environment:
      - APP_URL=https://auth.example.com
      - DB_PROVIDER=sqlite
      - DB_PATH=/app/data/pocket-id.db
      - ENCRYPTION_KEY_FILE=/run/secrets/pocket_id_encryption_key
    secrets:
      - pocket_id_encryption_key
    volumes:
      - ./data:/app/data
    networks:
      - proxy-tier
    deploy:
      resources:
        limits:
          memory: 256M
        reservations:
          memory: 64M

secrets:
  pocket_id_encryption_key:
    file: ./secrets/encryption_key.txt

networks:
  proxy-tier:
    external: true

1. Why Pocket-ID Replaces Legacy Enterprise SSO

In traditional setups, securing web services with SSO often meant deploying Authentik (requiring PostgreSQL, Redis, worker containers, and 1.5GB+ RAM) or Keycloak. Pocket-ID reimagines homelab identity:

Minimalist Resource Footprint: Runs entirely in a single Go binary backed by SQLite. Total baseline memory consumption is typically under 30MB.
Passwordless Passkey/WebAuthn Native: First-class support for hardware security keys (YubiKeys), Apple Touch ID, and Windows Hello, eliminating weak passwords.
Standardized OIDC: Emits compliant standard endpoints (/oauth2/token, /oauth2/authorize, /oauth2/userinfo) compatible with any application supporting generic OIDC (Paperless-ngx, Immich, Mealie, Wiki.js, Nextcloud, Grafana).
Hardened Distroless Architecture: The distroless image lacks shell binaries, package managers, and root daemons, minimizing CVE exposure.

2. Secret Generation and Deployment

Generate a cryptographically secure 32-byte encryption key for token encryption:

# 1. Create secrets directory with restrictive permissions
mkdir -p secrets data && chmod 700 secrets data

# 2. Generate random 32-character key
openssl rand -hex 32 > secrets/encryption_key.txt
chmod 600 secrets/encryption_key.txt

# 3. Ensure permissions match the non-root container UID (1000:1000)
chown -R 1000:1000 data secrets

3. Caddy Reverse Proxy Ingress

Route public traffic to Pocket-ID through Caddy with automatic HTTPS:

# /etc/caddy/Caddyfile
auth.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    reverse_proxy pocket-id:8080 {
        header_up X-Forwarded-Proto https
    }
}

4. Connecting Homelab Services via OIDC

Once Pocket-ID is initialized, navigate to the web dashboard and click Clients > Add Client. Set:

Name: Paperless-ngx (or your target app)
Callback URL: https://paperless.example.com/accounts/oidc/pocket-id/login/callback/

Copy the generated Client ID and Client Secret into your target service’s environment configuration to complete zero-trust SSO integration.