Pocket-ID
Docker app from junkerderprovinz's Repository
A small OpenID Connect provider that signs people in with passkeys instead of passwords.
Requirements
Overview
Readme
View on GitHub
Validate Upstream Pocket ID Image Unraid License
A plug-and-play Unraid Community Applications template for Pocket ID, the small OpenID
Connect provider that signs you in with passkeys, wrapping the official
pocketid/pocket-id image.
Maintained solo, in whatever spare time there is. Questions via the support thread, bugs, ideas and feature requests via GitHub issues. If it's useful to you, a coffee is always welcome.
Table of Contents
- What is this?
- Quick Start on Unraid
- Behind a reverse proxy
- Connecting an app
- Configuration
- Backups and the encryption key
- When something goes wrong
- How AI is used here
- Support this project
1. What is this?
Pocket ID is a login server for your other apps. Anything on your server that can sign in over OpenID Connect (the photo library, the dashboards, the hypervisor's web interface, the media server with an SSO plugin and plenty more) sends its users to Pocket ID, and Pocket ID asks for a passkey: the fingerprint reader on a laptop, the face unlock on a phone, a security key. There are no passwords in it at all, so there is nothing to reuse or phish.
It keeps users, groups and the list of apps that may sign in, and an audit log of every sign-in. Where the big identity suites want a database, a cache and an afternoon, this is one container with SQLite and around 20 MB of memory. It is BSD-2-Clause, written in Go and Svelte by Elias Schneider and contributors.
The template pins the image to v2, so updates follow every 2.x release but a future 3.0 does
not arrive overnight. When it ships, read its release notes and change the tag yourself.
2. Quick Start on Unraid
Apps and search for Pocket ID, then install.
Set App URL to the domain Pocket ID will live under, for example
https://id.example.com. Passkeys are bound to this domain, so settle on it before anyone signs up.Generate an Encryption Key in the Unraid terminal and paste it in:
openssl rand -base64 32Keep a copy in your password manager. Section 6 explains why.
Leave Data on
/mnt/user/appdata/pocket-idand the user on 99:100.Start it, set up the reverse proxy (next section), then open
https://id.example.com/setup. You create the first account there, which becomes the admin, and add its passkey right after.
Do the setup soon after the domain goes live. Until the first account exists, anyone who finds the address can create it.
Other Docker hosts
compose.yaml runs Pocket ID on any Linux server with Docker. Put it in a folder of its own, fill in every value marked required and start it with docker compose up -d. The data folder is created next to the file.
- Synology: in Container Manager, create a project from the file (DSM 7.2 or newer).
- Proxmox: run it in a VM or an LXC container that has Docker.
3. Behind a reverse proxy
Browsers only create passkeys over HTTPS, and only for the domain in App URL. Opening
http://<tower-ip>:1411 shows the pages, but every passkey prompt fails there. So Pocket ID
needs a reverse proxy with a certificate in front of it.
Nginx Proxy Manager: a proxy host for your domain, scheme http, the container's IP and port
1411, your certificate with Force SSL on. Under Advanced, larger buffers keep big OIDC
responses from failing with "upstream sent too big header":
proxy_busy_buffers_size 512k;
proxy_buffers 4 512k;
proxy_buffer_size 256k;
Trust Proxy: set it to true, or better to the proxy's own address. Without it, the audit
log and the rate limiter see every visitor as the proxy. If a second hop sits in front, such as a
Cloudflare tunnel container, list both addresses, separated by a comma.
Cloudflare: a tunnel route or an orange-cloud DNS record works without anything special. Pocket ID can also take the sign-in location from Cloudflare's headers instead of a GeoLite database (Cloudflare Location Headers), but only switch that on when every request comes through Cloudflare. Otherwise anyone on your network could send those headers themselves.
4. Connecting an app
In Pocket ID, open OIDC Clients, add one per app and enter the app's callback URL. The app's
documentation names it; it usually ends in something like /auth/callback or
/oauth2/callback. Pocket ID then shows a client ID and a client secret.
In the app, choose OpenID Connect (sometimes listed as OAuth or SSO) and give it:
| Field in the app | Value |
|---|---|
| Issuer or discovery URL | https://id.example.com or https://id.example.com/.well-known/openid-configuration |
| Client ID | from Pocket ID |
| Client secret | from Pocket ID |
| Scopes | openid profile email, plus groups if the app maps roles from groups |
New clients are restricted to the user groups you allow on them, so add the right group to the client or nobody gets in.
5. Configuration
| Setting | Default | What it does |
|---|---|---|
| WebUI | 1411 |
Web interface and OIDC endpoints. The reverse proxy points here. |
| Data | /mnt/user/appdata/pocket-id |
SQLite database, uploaded logos, GeoLite database. |
| App URL | https://id.example.com |
Public address with https://, no path. Required. |
| Encryption Key | - | Encrypts the signing keys and secrets in the database. Required, masked. |
| Trust Proxy | false |
true or the proxy addresses, so the real visitor address is logged. |
| Database Connection String | empty | Empty means SQLite. postgres://USER:PASSWORD@HOST:5432/DBNAME for PostgreSQL. |
| MaxMind License Key | empty | A free GeoLite2 key adds city and country to the audit log. |
| PUID / PGID | 99 / 100 |
The user the app runs as, nobody:users on Unraid. |
| Cloudflare Location Headers | false |
Location from Cloudflare's headers instead of GeoLite. |
| Audit Log Retention Days | 90 |
How long sign-in events are kept. |
| Disable UI Configuration | false |
true makes the settings page read-only and takes settings from environment variables. |
| Disable Analytics | false |
true stops the daily heartbeat (version and a random instance ID) to analytics.pocket-id.org. |
| Disable Version Check | false |
true stops asking GitHub for the latest release. |
| Log Level | info |
debug, info, warn or error. |
Email for sign-up invitations and login codes (SMTP), the look of the login page, LDAP sync and the rest live in Pocket ID's own settings page, not in the template. The upstream documentation lists every variable if you want to set one by hand under Add another Path, Port, Variable.
6. Backups and the encryption key
Everything Pocket ID knows is in the Data folder. Back it up like any other appdata folder with the container stopped, or let the built-in export write everything into one ZIP while it keeps running:
docker exec Pocket-ID /app/pocket-id export --path /app/data/pocket-id-export.zip
The backup is only half of it. The token signing keys inside are encrypted with the Encryption Key, so a restored database without the matching key is useless, and every app would have to be connected again. Keep the key next to the backup, in your password manager.
To change the key, do not just edit the field. Let Pocket ID re-encrypt its data first, then put the new key into the template and apply it:
docker exec -it Pocket-ID /app/pocket-id encryption-key-rotate --new-key <new key>
7. When something goes wrong
Lost your only passkey. Create a one-time sign-in link from the Unraid terminal, valid for an hour, and add a new passkey once you are in:
docker exec Pocket-ID /app/pocket-id one-time-access-token <username or email>
The log says "there's already one instance of Pocket ID running". The container was killed without a clean stop, and the previous run still holds its lock for about a minute. Wait a moment and start it again. A normal stop, restart or update through the Docker tab never runs into this.
"addgroup: gid '100' in use" at the top of the log is harmless. The image tries to create its
own group, finds Unraid's users group already on 100 and runs with that one.
The passkey prompt fails or never appears. Check that the browser's address bar shows exactly the domain in App URL, over HTTPS. A different subdomain, the bare IP or plain HTTP all fail.
8. How AI is used here
One knight builds this, and AI is one of the tools I work with, the same way I work with an editor or a compiler. It helps me write code and documentation and it checks my work, and that saves me a good many evenings. It does not make the decisions, though. I read and understand everything before it ships, and if something here breaks, that is on me and not on the tool.
You do not have to take my word for it. The code is open and every release note is written by hand. The issue tracker shows how problems actually get handled, including the ones I got wrong the first time. If you find something that is not right, open an issue and I will look at it.
9. Support this project
Pocket ID itself is Elias Schneider's and its contributors' work, BSD-2-Clause. What is maintained here is the Unraid template and this page.
Categories
Download Statistics
Total Downloads Over Time
Related apps
Explore more like this
Explore allLinks
Details
pocketid/pocket-id:v2Runtime arguments
- Web UI
http://[IP]:[PORT:1411]/- Network
bridge- Shell
sh- Privileged
- false
Template configuration
The web interface and the OIDC endpoints. Point your reverse proxy here. Opened directly over http://tower-ip:1411 the pages load, but passkeys fail.
- Target
- 1411
- Default
- 1411
- Value
- 1411
The SQLite database, uploaded logos and the GeoLite database. Back this folder up together with the encryption key.
- Target
- /app/data
- Default
- /mnt/user/appdata/pocket-id
- Value
- /mnt/user/appdata/pocket-id
The public address Pocket ID is reached at, with https:// and without a path. Passkeys are bound to this domain, so pick it before the first user signs up. Replace the example with your own domain.
- Target
- APP_URL
- Default
- https://id.example.com
- Value
- https://id.example.com
Encrypts the token signing keys and other secrets in the database. At least 16 characters; generate one with: openssl rand -base64 32. Losing it makes the existing data unreadable. To change it later, use the built-in encryption-key-rotate command rather than editing this field.
- Target
- ENCRYPTION_KEY
Set to true behind a reverse proxy so the audit log and rate limits see the visitor's address instead of the proxy's. Instead of true you can list the proxy addresses, separated by commas, for example 192.168.1.20.
- Target
- TRUST_PROXY
- Default
- false
- Value
- false
Leave empty for SQLite in the Data folder, which is plenty for a home server. For PostgreSQL: postgres://USER:PASSWORD@HOST:5432/DBNAME. Create the database and the user first.
- Target
- DB_CONNECTION_STRING
Optional. With a free GeoLite2 key from maxmind.com, the audit log shows the city and country of each sign-in. Without it, only the IP address is shown.
- Target
- MAXMIND_LICENSE_KEY
User the app runs as. 99 is nobody on Unraid, which owns the appdata share.
- Default
- 99
- Value
- 99
Group the app runs as. 100 is users on Unraid.
- Default
- 100
- Value
- 100
Take the sign-in location from the headers Cloudflare adds instead of GeoLite. Only switch it on when every request reaches Pocket ID through Cloudflare, since anyone else could set those headers themselves.
- Target
- CLOUDFLARE_LOCATION_HEADERS
- Default
- false|true
- Value
- false
How many days the audit log keeps sign-in events.
- Target
- AUDIT_LOG_RETENTION_DAYS
- Default
- 90
- Value
- 90
When true, application settings such as SMTP come from environment variables only and the settings page is read-only. Leave false to configure everything in the web interface.
- Target
- UI_CONFIG_DISABLED
- Default
- false|true
- Value
- false
Pocket ID sends a daily heartbeat with its version and a random instance ID to analytics.pocket-id.org, so the developers can count installs. Set to true to switch it off.
- Target
- ANALYTICS_DISABLED
- Default
- false|true
- Value
- false
Set to true to stop asking GitHub for the latest release, which the admin page uses to announce updates.
- Target
- VERSION_CHECK_DISABLED
- Default
- false|true
- Value
- false
How much the container log shows.
- Target
- LOG_LEVEL
- Default
- info|debug|warn|error
- Value
- info