6.7 KiB
title, description
| title | description |
|---|---|
| Pocket ID | Install Pocket ID, a lightweight self-hosted OIDC provider that lets you log in to your other apps with a passkey instead of a password. |
:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}
Pocket ID is a minimalist, self-hosted OIDC (OpenID Connect) provider built entirely around passkeys: instead of managing passwords, you and your users log in to compatible apps with a passkey (fingerprint, face unlock, or a hardware security key). It runs as a single lightweight container with no external database to manage, and it does exactly one thing well: issuing OIDC logins.
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.
Installation
Folder structure:
root
└── docker
└── pocket-id
├── compose.yaml
├── .env
└── data
::steps{level="3"}
Create the data folder
sudo mkdir -p /docker/pocket-id/data
Generate an encryption key
openssl rand -base64 32
Keep the output, you'll need it for the .env file below.
Deploy the stack
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
::
Set your environment variables
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.
Done !
::
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.
::
::steps{level="3"}
Add Pocket ID's network to SWAG
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.
::
Create the subdomain.conf file
In the Swag folders, create the file id.subdomain.conf:
::tip{icon=""} ✨ Tip: Use File Browser Quantum 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 (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.
Visit your new subdomain
Wait a few minutes, then open https://id.mydomain.com in your browser.
::caution
If it fails: check your firewall rules. ::
Done !
::
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:
::steps{level="3"}
Log in to Pocket ID
Go to https://id.mydomain.com and log in with your passkey.
Create the OIDC client
Go to Administration > OIDC Clients, then 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 your client credentials
Save, then copy the generated Client ID and Client Secret. You'll need them in the other app's configuration.
Done !
::
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.