Pocket ID: lightweight OIDC provider in one container

Why self-host your OIDC provider

What you get with a self-hosted OIDC IdP

• Centralised identity — a single account for Gitea, Nextcloud, Grafana and all OIDC-compatible services.
• Global revocation — disabling an account in Pocket ID cuts access to all connected applications at the next token renewal.
• Passkey authentication — Touch ID, Face ID or a FIDO2 key as the sole factor, with no password to transmit.
• No cloud dependency — your identities stay under your jurisdiction, with no per-user quota or per-action pricing.
• Minimal footprint — Pocket ID consumes less than 50 MB of RAM at idle, versus 300–600 MB for Authentik and 1–2 GB for Keycloak.
• Embedded SQLite — no external database engine to provision or back up separately.
• Back-channel logout (v2.18.0) — when a user is disabled or revokes a client, Pocket ID notifies registered applications and invalidates their server-side sessions.
• Single container — the entire service fits in a ~30 MB Docker image, with no Redis dependency and no separate worker.

Concrete prerequisites

Installing Pocket ID

1. 01

   Prepare the VPS and domain

   Order a VPS running Ubuntu 22.04 or Debian 12 with at least 512 MB of RAM. Create a DNS A record pointing auth.your-domain.com to your VPS IP address. This subdomain is the public URL of your Pocket ID instance — it must be reachable before the first configuration, as OIDC redirects depend on it.

   Install Docker and the Compose plugin:

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

2. 02

   Create the working directory

   On the server, create a dedicated directory:

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

3. 03

   Write the docker-compose.yml file

   Create /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.your-domain.com"
         TRUST_PROXY: "true"

   APP_URL must exactly match the public URL of your instance, including the https:// scheme. TRUST_PROXY: "true" tells Pocket ID to trust the X-Forwarded-* headers forwarded by the reverse proxy.

4. 04

   Configure the nginx reverse proxy

   Create the nginx vhost for auth.your-domain.com. Pocket ID listens on HTTP on port 1411; the reverse proxy handles TLS.

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

   Obtain the certificate with Certbot before reloading nginx:

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

5. 05

   Start the container

   From /opt/pocket-id:

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

   The log line Starting Pocket ID on :1411 confirms the server is ready. Visit https://auth.your-domain.com to complete the initial setup.

6. 06

   Create the admin account and register a passkey

   On the first visit, Pocket ID prompts you to create the administrator account. Enter your email, then immediately register a passkey: go to Settings → Passkeys → Add and follow your browser's prompt (Touch ID, Windows Hello, or a FIDO2 key). Once the passkey is registered, it is the only factor required for subsequent logins.

7. 07

   Register your first OIDC application

   In the administration interface, open OIDC Clients → New client. Fill in:
   - Name: a readable identifier for the application (e.g. Gitea)
   - Callback URL: the redirect URL declared in the client application (e.g. https://git.your-domain.com/user/oauth2/pocket-id/callback)

   Pocket ID v2.18.0 automatically creates a client_secret at creation time — retrieve it immediately, as it will not be displayed in plain text again.

   Note the Client ID and the discovery URL https://auth.your-domain.com/.well-known/openid-configuration: these are the two values to enter in the client application.

8. 08

   Test the flow from the client application

   In Gitea, go to Administration → Authentication Sources → Add → OAuth2. Select OpenID Connect as the provider, fill in the Client ID, Client Secret and the discovery URL. Trigger a test login: the browser should be redirected to auth.your-domain.com, prompt for the registered passkey, and then redirect back to Gitea with the user logged in.

Post-installation configuration

Troubleshooting

Common errors and solutions

• 502 Bad Gateway on all pages — most common cause: nginx buffers are too small for Pocket ID's OIDC response headers. Add proxy_buffer_size 256k, proxy_buffers 4 512k and proxy_busy_buffers_size 512k in your location / block and reload nginx.
• redirect_uri_mismatch during login — the Callback URL declared in Pocket ID does not exactly match the one sent by the client application. Check for a trailing slash, http vs https scheme, and the port number. The match must be exact, character for character.
• invalid_client at code exchange — the client_secret sent by the application does not match. In v2.18.0, Pocket ID creates a secret automatically at client creation; if you did not save it, regenerate one from the client record in the administration panel.
• Passkey rejected: NotAllowedError — your browser cannot access WebAuthn APIs without HTTPS. Verify that APP_URL is set to https://... and that the TLS certificate is valid (not self-signed, not expired); Certbot must have issued a certificate for the correct domain.
• Sessions are not invalidated after revocation — back-channel logout requires the client application to declare a Backchannel Logout URL in its OIDC record. Without this URL, Pocket ID cannot notify the application; existing sessions will expire at their natural lifetime. Verify the field is filled in and reachable from the Pocket ID container.

Pocket ID, Authentik, Keycloak, Authelia: which to choose

Scroll the table

Conclusion