docudjeex/content/en/3.serveex/3.security/3.pocket-id.md

title, description

title	description
Pocket ID	Install Pocket ID, a lightweight self-hosted OIDC provider using passkeys, as a minimal alternative to Authentik for single sign-on.

:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}

Pocket ID

::note 🎯 Objectives:

• Install Pocket ID
• Create your admin account and first passkey
• Register an OIDC client for another app ::

Pocket ID is a minimalist, self-hosted OIDC (OpenID Connect) provider. Unlike Authentik, it doesn't try to do everything: no LDAP, no proxy outposts, no complex flow builder. It only does one thing: let you log in to OIDC-compatible apps with a passkey (fingerprint, face unlock, or security key) instead of a password.

This makes it a good fit if you just need a simple, fast SSO backend, for example to pair with TinyAuth as a lightweight forward-auth setup, or to log in directly to apps that natively support OIDC.

• Pocket ID documentation
• Pocket ID on GitHub

Installation

Folder structure:

root
└── docker
    └── pocket-id
        ├── compose.yaml
        ├── .env
        └── data

Create the data folder:

sudo mkdir -p /docker/pocket-id/data

Generate an encryption key for the .env file:

openssl rand -base64 32

Open Dockge, click compose, name the stack pocket-id, and add the following config:

---
services:
  pocket-id:
    image: pocketid/pocket-id:v2
    container_name: pocket-id
    restart: unless-stopped
    env_file:

      - .env
    volumes:

      - /docker/pocket-id/data:/app/data
    ports:

      - 1411:1411
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1411/healthz"]
      interval: 90s
      timeout: 5s
      retries: 3

::tip ✨ Add the Watchtower label to automate updates:

services:
  pocket-id:
    #...
    labels:

      - com.centurylinklabs.watchtower.enable=true

::

Fill in the .env file:

APP_URL=https://id.mydomain.com
ENCRYPTION_KEY=
TRUST_PROXY=true

Variable	Value	Example
APP_URL{lang=properties}	The public URL you'll use to reach Pocket ID (see exposure below)	https://id.mydomain.com
ENCRYPTION_KEY{lang=properties}	The key generated above	Q2pVEqsTNRkJSO9SkJzU3KZ2...
TRUST_PROXY{lang=properties}	Required since Pocket ID sits behind Swag	true

Deploy the stack. The local interface is available at http://yourserverip:1411.

First login

Pocket ID doesn't use passwords: your first account is created with a passkey, which your browser or OS will generate for you (Windows Hello, Touch ID, a phone, or a hardware key like a YubiKey).

• Go to http://yourserverip:1411/setup
• Follow the prompts to create your admin account and register your first passkey

::note

Since APP_URL is already set to your future public domain, passkey registration may ask you to open Pocket ID from that domain instead. Expose it first (see below) if setup doesn't complete locally. ::

Exposing Pocket ID with Swag

Other apps need to reach Pocket ID over HTTPS to complete the OIDC login flow, so it must be exposed even if you only use it from home.

::note

We assume you have the subdomain id.mydomain.com with a CNAME pointing to mydomain.com in your DNS zone. And of course, unless you use Cloudflare Zero Trust, your box's port 443 must be forwarded to your server's port 443 in NAT rules. ::

Go to Dockge and edit SWAG's compose file by adding Pocket ID's network:

services:
  swag:
     container_name: # ...
      # ... 
     networks:                # Attach container to custom network 
      # ...           

      - pocket-id             # Name of the declared network

networks:                     # Define the custom network
  # ...
  pocket-id:                  # Declared network name
    name: pocket-id_default   # Actual external network name
    external: true            # Marks it as externally defined

Redeploy the stack and wait for SWAG to be fully operational.

::note

Here we assume the Pocket ID network name is pocket-id_default. You can check the connection by visiting SWAG's dashboard at http://yourserverip:81. ::

In the Swag folders, create the file id.subdomain.conf:

::tip{icon=""} ✨ Tip: Use File Browser to navigate and edit files instead of using terminal commands. ::

sudo nano /docker/swag/config/nginx/proxy-confs/id.subdomain.conf

Paste the following configuration:

## Version 2023/12/19

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name id.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app pocket-id;
        set $upstream_port 1411;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

::caution

Don't put Pocket ID behind another authentication layer (Authentik, TinyAuth, HTTP auth...). It's the identity provider itself, so locking it away would prevent anyone, including you, from logging in. ::

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

Wait a few minutes, then open https://id.mydomain.com in your browser.

::caution

If it fails: check your firewall rules. ::

Registering an OIDC client

To let another app (e.g. TinyAuth) log in through Pocket ID, you need to register it as an OIDC client:

• Go to https://id.mydomain.com
• Log in with your passkey
• Go to Administration > OIDC Clients
• Click Add OIDC Client
• Fill in a name (e.g. TinyAuth) and the app's callback URL (provided by the app you're protecting)
• Save, then copy the generated Client ID and Client Secret. You'll need them in the other app's configuration

And that's it! Pocket ID is ready to act as your OIDC provider. Head to the TinyAuth guide to use it as a forward-auth login page for the rest of your apps.