Skip to content

PocketID — Runbook

Routine Tasks

Add a passkey (new device)

  1. Go to https://auth.eva-00.network
  2. Sign in → Profile → Add passkey

Rotate the API key

  1. Admin panel → API Keys → revoke old key → create new key with no expiry
  2. Store new key in Vault: vault kv patch secret/pocketid api_key=<new-key>
  3. Re-run the pocketid-setup workflow if any OIDC client secrets need refreshing

Add a new OIDC client

  1. Add the client config to ansible/playbooks/pocketid-setup.yml
  2. Run pocketid-setup workflow from Forgejo Actions (workflow_dispatch)

Rotate all homelab-sso secrets (full rotation)

homelab-sso in Vault holds 15 keys. When rotating, write all at once via vault-write.yml with patch: "false". Do not use patch mode for rotation — use a single full write with all keys, then redeploy all affected services.

Keys in secret/homelab-sso: - pocketid_client_id / pocketid_client_secret — from PocketID OIDC client - Cookie secrets (one per service): n8n_cookie_secret, open_webui_cookie_secret, glance_cookie_secret, gatus_cookie_secret, the_lounge_cookie_secret, filedump_cookie_secret, homebridge_cookie_secret, qbitwebui_cookie_secret, seedbox_cookie_secret, normal_cookie_secret, grafana_cookie_secret - grafana_admin_password — Grafana admin password (read by loki-stack) - n8n_webhook_token — token gatus uses to call n8n webhooks

To get current values before rotating: read from deployed .env files on the relevant LXCs (e.g. ssh [email protected] "pct exec 119 -- cat /opt/homelab/oauth2-gateway/.env"). The pocketid_client_id/pocketid_client_secret can only be retrieved from the live .env or regenerated via pocketid-setup workflow.

After writing, redeploy: oauth2-gateway, n8n, open-webui, glance, gatus, the-lounge, qbitwebui, seedbox, loki-stack.

Logs

Log Contents Location Loki query Format
Application OIDC auth flows, client registrations, passkey events, errors Docker (LXC 123) stdout {job="auth", container="pocketid"} Plain text

Notes: - SSH fallback: ssh [email protected] "pct exec 123 -- docker logs pocketid"

Troubleshooting

SSO login fails for a service

  1. Check PocketID logs for OIDC errors
  2. Verify the client secret in Vault matches what's deployed: run the relevant service's deploy workflow to re-sync credentials
  3. If client secret is stale, re-run pocketid-setup workflow, then redeploy the service

Passkey not working on a new device

  • Add a new passkey via Profile on a device where you can already authenticate
  • If locked out entirely, access the admin panel directly at http://192.168.1.123:1411/admin using the admin credentials from Vault