228 lines
6.6 KiB
Markdown
228 lines
6.6 KiB
Markdown
---
|
|
title: Pocket ID
|
|
description: 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](https://pocket-id.org) 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](/serveex/security/tinyauth) as a lightweight forward-auth setup, or to log in directly to apps that natively support OIDC.
|
|
|
|
- [Pocket ID documentation](https://pocket-id.org/docs)
|
|
- [Pocket ID on GitHub](https://github.com/pocket-id/pocket-id)
|
|
|
|
## Installation
|
|
|
|
::file-tree
|
|
---
|
|
tree:
|
|
/:
|
|
- docker:
|
|
- pocket-id:
|
|
- compose.yaml
|
|
- .env
|
|
- data/
|
|
---
|
|
::
|
|
|
|
::steps{level="3"}
|
|
### Create the data folder
|
|
|
|
```bash [Terminal]
|
|
sudo mkdir -p /docker/pocket-id/data
|
|
```
|
|
|
|
### Generate an encryption key
|
|
|
|
```bash [Terminal]
|
|
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:
|
|
|
|
```yaml [compose.yaml]
|
|
---
|
|
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{icon=""}
|
|
✨ Add the Watchtower label to automate updates:
|
|
|
|
```yaml [compose.yaml]
|
|
---
|
|
services:
|
|
pocket-id:
|
|
#...
|
|
labels:
|
|
- com.centurylinklabs.watchtower.enable=true
|
|
```
|
|
::
|
|
|
|
### Set your environment variables
|
|
|
|
Fill in the `.env` file:
|
|
|
|
```properties [.env]
|
|
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](/general/networking/dns). And of course, [unless you use Cloudflare Zero Trust](/serveex/security/cloudflare), your box's port `443` must be forwarded to your server's port `443` in [NAT rules](/general/networking/nat).
|
|
::
|
|
|
|
::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:
|
|
|
|
```yaml [compose.yaml]
|
|
---
|
|
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](/serveex/files/file-browser-quantum) to navigate and edit files instead of using terminal commands.
|
|
::
|
|
|
|
```bash [Terminal]
|
|
sudo nano /docker/swag/config/nginx/proxy-confs/id.subdomain.conf
|
|
```
|
|
|
|
Paste the following configuration:
|
|
|
|
```nginx [id.subdomain.conf]
|
|
## 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](/serveex/security/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](/serveex/security/tinyauth) to use it as a forward-auth login page for the rest of your apps.
|