PocketID — Setup
Passkey-based OIDC provider. All SSO-protected services authenticate via PocketID using WebAuthn passkeys. Runs as a Docker container on LXC 123 (auth).
Infrastructure
| Host | Internal | URL |
|---|---|---|
| Docker (LXC 123) | 192.168.1.123:1411 | https://auth.eva-00.network |
Observability
Logs
PocketID logs are collected via Grafana Alloy Docker discovery and shipped to Loki.
| Query | Purpose |
|---|---|
{container="pocketid"} |
All container output |
{container="pocketid"} \|= "error" |
Errors only |
{container="pocketid"} \|= "unauthorized" |
Authentication failures |
Access: Grafana → Explore → Loki → Enter query
Metrics
PocketID does not export Prometheus metrics by default. Use Loki logs to diagnose authentication issues.
IaC
| Artifact | Path |
|---|---|
| Setup playbook | ansible/playbooks/pocketid-setup.yml |
| Setup workflow | .forgejo/workflows/pocketid-setup.yml |
Secrets (stored in Vault)
secret/pocketid → encryption_key, api_key
OIDC clients
OIDC clients are managed via the PocketID admin API (key in Vault at secret/pocketid → api_key). Client credentials are stored in Vault under per-service paths.
Current OIDC clients: Forgejo, Grafana, code-server, homelab-sso (shared), paperless, and others.
To add a new client: POST /api/oidc/clients, then POST /api/oidc/clients/{id}/secret to generate credentials. See reference.md for full API examples.
User Groups
Groups control access to OIDC clients via isGroupRestricted. When enabled on a client, only users in allowed groups can log in.
| Group | Members | Purpose |
|---|---|---|
| Admin | holo | Full access to all services |
| Familia | milton | Family access to shared services (Paperless, etc.) |
Group IDs (current)
| Group | ID |
|---|---|
| Admin | d108cafb-2d82-419b-8fb0-12e730ab51f5 |
| Familia | f73525ab-11c7-46da-bfe4-81cdfa335fec |
Adding a new family member
- Create user via API (see reference.md)
- Add to Familia group via API
- They visit PocketID, register a passkey on their device — no passwords
- They can now log in to any group-restricted service that allows Familia
Users
| Username | Groups | Admin | |
|---|---|---|---|
| holo | [email protected] | Admin | Yes |
| milton | [email protected] | Familia | No |