tutorial

Monitoring Pocket ID with Vigilmon

Pocket ID is a self-hosted OIDC provider and SSO server — but when your identity layer goes down, every app that depends on it goes with it. Here's how to monitor Pocket ID's auth endpoints, OIDC discovery, and token issuance with Vigilmon.

Pocket ID is a lightweight, self-hosted OIDC identity provider written in Go. It runs on port 1411 and handles authentication for every application in your stack that delegates SSO to it. That makes it uniquely critical: if Pocket ID goes down, users can't log in to any connected app. Vigilmon gives you the visibility you need — checking the auth server, OIDC discovery document, token endpoint, and audit log service before your users notice anything is wrong.

What You'll Set Up

  • HTTP uptime monitor for the Pocket ID web server
  • OIDC discovery endpoint health check
  • OAuth2 token issuance endpoint monitor
  • User account management API monitor
  • Client app registration health check
  • Audit log service availability monitor

Prerequisites

  • Pocket ID running and accessible (default port 1411)
  • A free Vigilmon account

Step 1: Monitor the Pocket ID Web Server

Pocket ID's web interface and API both run on port 1411. Start with a basic uptime check:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the URL: http://your-server:1411 (or your domain if you proxy Pocket ID behind nginx/Caddy).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If you proxy Pocket ID behind a reverse proxy, use the public URL instead of the direct port:

https://auth.yourdomain.com

A 200 response on the root path confirms the Go HTTP server is alive and the reverse proxy is correctly forwarding traffic.

Step 2: Monitor the OIDC Discovery Endpoint

The OIDC discovery document at /.well-known/openid-configuration is the first thing every OIDC client fetches. If this endpoint returns an error, all client apps that auto-configure via discovery will break immediately.

  1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
  2. URL: https://auth.yourdomain.com/.well-known/openid-configuration
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200.
  5. Under Response validation, add a body contains check for "issuer".
  6. Click Save.

The body check ensures Pocket ID is returning a valid JSON document with the issuer field — not a cached error page from a misconfigured proxy.

Verify the endpoint manually before adding the monitor:

curl -s https://auth.yourdomain.com/.well-known/openid-configuration | jq .issuer
# "https://auth.yourdomain.com"

Step 3: Monitor the OAuth2 Token Issuance Endpoint

The /api/oidc/token endpoint processes every login. A slow or unresponsive token endpoint means users see login failures even when the UI loads fine.

  1. Add a new HTTP / HTTPS monitor.
  2. URL: https://auth.yourdomain.com/api/oidc/token
  3. Set Expected HTTP status to 400 (the endpoint rejects unauthenticated GET requests with 400 or 405, confirming the server is up and routing correctly without needing real credentials).
  4. Set Check interval to 1 minute.
  5. Click Save.

This "probe for a known error" pattern is common for auth endpoints — you verify the server is alive and responding without triggering actual authentication logic.

Alternatively, if you have a test client configured in Pocket ID, use the client credentials flow:

curl -s -X POST https://auth.yourdomain.com/api/oidc/token \
  -d "grant_type=client_credentials&client_id=test&client_secret=secret" \
  | jq .token_type
# "Bearer"

Use this as a synthetic transaction monitored via a Vigilmon webhook or external script calling the Vigilmon heartbeat API.

Step 4: Monitor the User Account Management API

Pocket ID exposes a REST API for user and client management. Monitor the health of this API:

  1. Add a new HTTP / HTTPS monitor.
  2. URL: https://auth.yourdomain.com/api/health (or /api/ if Pocket ID doesn't expose a dedicated health route — check its current version's API docs).
  3. If no dedicated health endpoint exists, monitor the admin UI path instead: https://auth.yourdomain.com/admin
  4. Set Expected HTTP status to 200.
  5. Click Save.

Check the Pocket ID API documentation for the version you're running to confirm available health or status endpoints, as these may change between releases.

Step 5: Monitor Client App Registration Health

Pocket ID stores client registrations — if the underlying SQLite database becomes corrupted or the file system fills up, client lookups will start failing even though the HTTP server is still responding.

Add a monitor that checks a client-specific OIDC endpoint to verify the data layer is intact:

  1. In Pocket ID admin, note the client ID of a registered app (e.g. my-app).
  2. Add an HTTP / HTTPS monitor for the JWKS endpoint: https://auth.yourdomain.com/api/oidc/jwks
  3. Set Expected HTTP status to 200.
  4. Add a body contains check for "keys".
  5. Click Save.

The JWKS endpoint requires Pocket ID to load its signing keys from storage. A failed JWKS response often indicates a storage or key-loading issue before any login attempt fails.

Step 6: Monitor the Audit Log Service

Pocket ID logs authentication events. While a failing audit log won't immediately prevent logins, it's an early warning that disk space or file I/O is degrading. Monitor disk health on the host Pocket ID runs on:

Use a cron heartbeat to confirm Pocket ID's log rotation or a companion health script is running:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 60 minutes.
  3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/abc123.
  4. Add a cron job on your Pocket ID host:
# /etc/cron.hourly/pocket-id-health
#!/bin/bash
# Check Pocket ID is responding and disk has headroom
if curl -sf http://localhost:1411/.well-known/openid-configuration > /dev/null; then
  DISK_USAGE=$(df /var/lib/pocket-id | awk 'NR==2{print $5}' | tr -d '%')
  if [ "$DISK_USAGE" -lt 85 ]; then
    curl -s https://vigilmon.online/heartbeat/abc123
  fi
fi

This heartbeat only fires when both the OIDC discovery endpoint responds and disk usage is below 85%. Silence triggers a Vigilmon alert.

Step 7: Configure Alert Channels

Because Pocket ID is the authentication layer for other services, alerts need to be immediate:

  1. Go to Alert Channels in Vigilmon and add Slack, PagerDuty, or email.
  2. Set Consecutive failures before alert to 1 on the OIDC discovery and token endpoint monitors — don't wait for a second failure when auth is broken.
  3. Set it to 2 on the web server monitor (a single missed probe may be a transient network hiccup).

Set up a dedicated Pocket ID alert channel group so auth alerts are never buried in general infrastructure noise.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server | https://auth.yourdomain.com | Pocket ID process crash, proxy misconfiguration | | OIDC discovery | /.well-known/openid-configuration | Client auto-configuration failures | | Token endpoint | /api/oidc/token | Login failures, token issuance errors | | JWKS endpoint | /api/oidc/jwks | Key loading / storage failures | | Cron heartbeat | Heartbeat URL | Disk full, audit log failure, process hanging |

Pocket ID's simplicity — a single Go binary, SQLite storage — is a feature, but it means there's no built-in health dashboard. With Vigilmon checking every layer of the auth stack, you'll know about identity provider failures before any of your users hit a login error.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles