---
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.

![pocketid](/img/serveex/pocketid.png)

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:
  /:
    - srv:
      - docker:
        - pocket-id:
          - compose.yaml
          - .env
          - data/
---
::

::steps{level="3"}
### Create the data folder

```bash [Terminal]
sudo mkdir -p /srv/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:
      - /srv/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="" to="/serveex/files/file-browser-quantum"}
✨ __Tip:__ Use **File Browser Quantum** to navigate and edit files instead of using terminal commands.
::

```bash [Terminal]
sudo nano /srv/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 !
::

## Connecting Pocket ID to TinyAuth
[TinyAuth](/serveex/security/tinyauth) can delegate its login to Pocket ID instead of (or alongside) its local username/password, so anyone visiting a protected app authenticates with a passkey and gets forwarded through.

::steps{level="3"}
### Register TinyAuth as an OIDC client

[Register an OIDC client](#registering-an-oidc-client) named `TinyAuth`, using this callback URL:

```text
https://tinyauth.mydomain.com/api/oauth/callback/pocketid
```

### Add the Pocket ID provider in TinyAuth

Copy the __Client ID__ and __Client Secret__ Pocket ID gives you, then edit TinyAuth's `.env` file:

```bash [Terminal]
sudo nano /srv/docker/tinyauth/.env
```

Add the following:

```properties [.env]
TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=Pocket ID
TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID=
TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET=
TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.mydomain.com/authorize
TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=https://id.mydomain.com/api/oidc/token
TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=https://id.mydomain.com/api/oidc/userinfo
TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://tinyauth.mydomain.com/api/oauth/callback/pocketid
TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile
```

| Variable | Value |
|----------|-------|
| `CLIENTID`{lang=properties} | The client ID copied from Pocket ID |
| `CLIENTSECRET`{lang=properties} | The client secret copied from Pocket ID |
| `AUTHURL` / `TOKENURL` / `USERINFOURL`{lang=properties} | Pocket ID's public URL, with the paths shown above |

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

### Redeploy the stack

Redeploy the TinyAuth stack. On your next visit to `https://tinyauth.mydomain.com`, you'll see a "Login with Pocket ID" option alongside the local login form.

::tip{icon=""}
✨ To skip straight to Pocket ID and hide the local login form, add `TINYAUTH_OAUTH_AUTOREDIRECT=pocketid` to the same `.env` file.
::

### Done !
::

That's it! TinyAuth now offers passwordless login via Pocket ID for every app it protects.
