---
title: Pocket ID
description: 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](https://pocket-id.org) is a minimalist, self-hosted OIDC (OpenID Connect) provider. Unlike [Authentik](/serveex/advanced/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](/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
Folder structure:
```text [Directory tree]
root
└── docker
    └── pocket-id
        ├── compose.yaml
        ├── .env
        └── data
```

Create the data folder:

```bash [Terminal]
sudo mkdir -p /docker/pocket-id/data
```

Generate an encryption key for the `.env` file:

```bash [Terminal]
openssl rand -base64 32
```

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
✨ Add the Watchtower label to automate updates:

```yaml [compose.yaml]
services:
  pocket-id:
    #...
    labels:

      - com.centurylinklabs.watchtower.enable=true
```
::

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

## 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).
::

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

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

::tip{icon=""}
✨ __Tip:__ Use [File Browser](/serveex/files/file-browser) 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 (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](/serveex/security/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](/serveex/security/tinyauth) to use it as a forward-auth login page for the rest of your apps.
