Remote-Pulse PocketID OIDC Setup¶

F5-1 implementation. Configure PocketID OIDC client for Remote-Pulse web dashboard.

Prerequisites¶

PocketID running at https://pocketid.monxas.casa
Admin access to PocketID UI
Caddy LXC 270/271 with snippet deployed

Steps¶

1. Create OIDC Client in PocketID¶

Login to PocketID admin UI: https://pocketid.monxas.casa
Navigate to Clients section
Click Add Client
Fill in details:
Client ID: remote-pulse-web
Client Name: Remote-Pulse Dashboard
Client Type: Confidential
Redirect URIs:
- https://dash.rp.monxas.casa/callback
- http://localhost:8080/callback (dev)
Scopes: openid, profile, email
Logo URI: https://rp.monxas.casa/static/logo.png (optional)
Click Save
Copy the generated Client Secret

2. Store Client Secret in SOPS¶

cd ~/docs-repo
sops secrets/remote-pulse.sops.yaml

Add/update:

pocketid_client_id: remote-pulse-web
pocketid_client_secret: <CLIENT_SECRET>

Save and exit.

3. Deploy Caddy Snippet¶

# Snippet already created at ansible/roles/caddy_lxc/files/snippets/rp-dashboard.caddy
# Deploy to LXC 270/271
ansible-playbook playbooks/caddy_lxc.yml

4. Configure Remote-Pulse Server¶

SSH to LXC 280:

ssh [email protected]
cd /opt/remote-pulse/server

Edit .env:

POCKETID_BASE_URL=https://pocketid.monxas.casa
POCKETID_CLIENT_ID=remote-pulse-web
POCKETID_CLIENT_SECRET=<CLIENT_SECRET>

Restart server:

systemctl restart rp-server

5. Test Authentication Flow¶

Open browser: https://dash.rp.monxas.casa
Should redirect to PocketID login
Login with passkey ([email protected])
Should redirect back to dashboard
Verify user info in top-right corner

6. Grant User Access to Groups¶

First login creates user with viewer role and empty accessible_groups.

Admin must grant groups:

ssh [email protected]
cd /opt/remote-pulse/server
source .venv/bin/activate

# Grant access to family group
python -m rp_server.admin users grant [email protected] --group=family

# Promote to admin role
python -m rp_server.admin users grant [email protected] --role=admin

User Roles¶

admin: Full access to all groups, can generate enrollment links
operator: Access to assigned groups, can issue commands
viewer: Read-only access to assigned groups

Troubleshooting¶

401 Unauthorized on /dash¶

Symptom: Browser shows "Authentication required" error.

Cause: PocketID forward_auth headers not present.

Fix: 1. Check Caddy logs: journalctl -u caddy -f 2. Verify PocketID is running: curl -k https://pocketid.monxas.casa/health 3. ⚠️ PocketID (v2) no tiene endpoint forward-auth — /forward-auth devuelve el SPA (HTTP 200) siempre, así que un curl de prueba "pasa" siempre y no valida nada. La protección real de dash.rp.monxas.casa debe venir de Cloudflare Access (borde) o de OIDC a nivel de app, no de forward_auth.

User has empty accessible_groups¶

Symptom: Dashboard shows "No hosts found".

Cause: New users default to empty groups.

Fix: Grant groups via CLI (see step 6 above).

bcrypt Client Secret Mismatch¶

Symptom: PocketID returns "Invalid client secret" during token exchange.

Cause: bcrypt hash corruption via SSH heredoc (see memory oidc_pocketid_apps.md).

Fix: Regenerate client secret in PocketID UI, update SOPS, redeploy.

References¶

ADR-0008 F5: Web dashboard + PocketID multi-user
Memory: oidc_pocketid_apps.md (PocketID integration patterns)
Caddy forward_auth: https://caddyserver.com/docs/caddyfile/directives/forward_auth