跳至主要内容

Pocket ID：以 Passkey 為核心的輕量 OIDC 認證服務

Pocket ID 是一款極簡、輕量的開源 OIDC (OpenID Connect) 身分提供者 (Identity Provider)，完全以 Passkey (WebAuthn) 作為核心驗證方式，沒有傳統密碼的繁瑣與安全隱患。

在 Homelab 中，可以透過 Pocket ID 作為統一身分中心，為所有內部服務、自建網頁與應用程式加上無密碼身分驗證鎖。

為什麼選擇 Pocket ID？​

  1. 純 Passkey 設計：註冊與登入直接使用 Face ID、Touch ID、Windows Hello 或硬體金鑰，免除記密碼與 2FA 驗證碼的步驟。
  2. 輕量極簡：資源佔用極低，預設採用 SQLite 單一檔案儲存即可穩定運行。
  3. 標準 OIDC 協議：支援標準 OIDC 發現機制 (/.well-known/openid-configuration)，相容絕大多數開源軟體與認證庫。
  4. 絕佳的開發者整合：在自建 Web 專案中，搭配 Better Auth 或 NextAuth 即可在數分鐘內完成 OIDC 接入。

部署步驟 (Docker Compose)​

Pocket ID 支援 SQLite（單機推薦）與 PostgreSQL 兩種儲存方案。

1. 建立目錄與環境變數​

sudo mkdir -p /opt/stacks/pocket-id/data
cd /opt/stacks/pocket-id

產生 32 位元加密金鑰：

openssl rand -base64 32

建立 .env 檔案：

APP_URL=https://auth.yourdomain.com
TRUST_PROXY=true
PUID=1000
PGID=1000
ENCRYPTION_KEY=填入上方產生的base64字串

# 使用 SQLite
DB_PROVIDER=sqlite
DB_CONNECTION_STRING=data/pocket-id.db

注意：APP_URL 必須是實際透過 HTTPS 訪問的網域名稱，WebAuthn/Passkey 規格要求必須在 HTTPS 環境下運作。

2. 建立 compose.yaml​

services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v1
    container_name: pocket-id
    restart: unless-stopped
    env_file: .env
    ports:
      - "1411:1411"
    volumes:
      - "./data:/app/data"
    healthcheck:
      test: ["CMD", "/app/pocket-id", "healthcheck"]
      interval: 90s
      timeout: 5s
      retries: 2
      start_period: 10s

3. 啟動服務​

sudo docker compose up -d

啟動後，透過反向代理（Nginx Proxy Manager / Traefik / Caddy）將 auth.yourdomain.com 轉發至 http://pocket-id:1411，並配置 SSL 憑證。

在瀏覽器訪問 https://auth.yourdomain.com 完成管理員註冊並綁定第一個 Passkey。

各種應用串接範例​

1. 在 Pocket ID 建立 OIDC Client​

  1. 進入 Pocket ID 後台 -> OIDC Clients -> Add Client。
  2. 填寫名稱與對應應用的 Redirect URL (回呼網址)。
  3. 取得 Client ID 與 Client Secret。

2. 搭配 Better Auth 串接範例 (TypeScript / Next.js)​

在專案中使用 Better Auth 的 Generic OAuth / OIDC 插件接入：

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  socialProviders: {
    custom: [
      {
        providerId: "pocket-id",
        name: "Pocket ID",
        clientId: process.env.POCKET_ID_CLIENT_ID!,
        clientSecret: process.env.POCKET_ID_CLIENT_SECRET!,
        authorizationUrl: "https://auth.yourdomain.com/authorize",
        tokenUrl: "https://auth.yourdomain.com/api/oidc/token",
        userInfoUrl: "https://auth.yourdomain.com/api/oidc/userinfo",
        scopes: ["openid", "profile", "email"],
      },
    ],
  },
});

3. 搭配常見開源服務​

在其他支援 OIDC 的自託管服務中，填入以下共通參數即可完成整合：

  • Issuer URL：https://auth.yourdomain.com
  • Authorization URL：https://auth.yourdomain.com/authorize
  • Token URL：https://auth.yourdomain.com/api/oidc/token
  • Userinfo URL：https://auth.yourdomain.com/api/oidc/userinfo
  • Scopes：openid profile email

相關連結​