tutorial

How to Monitor Pomerium with Vigilmon

Pomerium is your zero-trust access proxy — when any of its services fail, identity-aware access to your internal applications stops working. Here's how to monitor Pomerium's proxy, authenticate, authorize, and databroker services with Vigilmon.

Pomerium is a zero-trust reverse proxy that provides identity-aware access control to internal applications without a VPN. It intercepts every request, verifies identity through an upstream OIDC provider, enforces policy rules, and only then forwards the request to the upstream service. This architecture means that when Pomerium fails — even partially — access to every protected application stops working simultaneously for everyone trying to reach it from outside.

Vigilmon gives you external visibility into Pomerium's proxy health, authenticate service availability, authorize service status, and databroker connectivity. This tutorial walks through monitoring a production Pomerium deployment with multiple service components.

Why Monitoring Pomerium Matters

Pomerium's zero-trust architecture enforces security at the network edge. The consequences of its failure are immediate and broad:

  • Proxy service failure — every application behind Pomerium becomes unreachable; users see connection errors, not login prompts
  • Authenticate service down — users can no longer complete the OIDC login flow; existing sessions may continue briefly (depending on cookie settings) but no new logins succeed
  • Authorize service failure — policy evaluation stops; Pomerium may fail closed (deny all) or fail open depending on your configuration
  • Databroker unavailability — session data, device credentials, and directory sync state become inaccessible; session verification fails for existing sessions
  • Identity provider outage — Pomerium depends on an upstream OIDC provider; if it is unreachable, authentication cannot complete

Pomerium can be deployed as a single all-in-one binary or as separate services (proxy, authenticate, authorize, databroker). Both deployment modes need distinct health checks because the failure modes differ.

Step 1: Understand Pomerium's Service Architecture

Pomerium exposes the following health check endpoints by default:

| Service | Default Port | Health Endpoint | |---|---|---| | Proxy | 443 (HTTPS) | /ping | | Authenticate | 443 on auth subdomain | /ping | | Authorize | 5443 (gRPC/HTTPS) | /healthz | | Databroker | 5443 (gRPC/HTTPS) | /healthz |

In all-in-one deployments, all services share a single port and the /ping endpoint covers all of them. In split deployments, each service runs independently and must be monitored separately.

Verify the proxy health endpoint is accessible:

# All-in-one or proxy service
curl -i https://pomerium.example.com/ping
# HTTP/1.1 200 OK
# OK

# Authenticate service (on its own subdomain in split mode)
curl -i https://authenticate.pomerium.example.com/ping
# HTTP/1.1 200 OK
# OK

Step 2: Monitor the Proxy Health Endpoint

The proxy service is the front door to all protected applications. Monitoring /ping confirms that the proxy is accepting connections, TLS is valid, and the core routing layer is running.

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to: https://pomerium.example.com/ping
  4. Set the check interval to 1 minute
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: OK
    • Response time threshold: 500ms
  6. Set the monitor name: [pomerium-proxy] /ping
  7. Assign your primary alert channel (P1 — PagerDuty + Slack)
  8. Save

The /ping endpoint bypasses authentication and policy evaluation intentionally — it is designed to be probed without credentials.

What the Proxy Monitor Catches

| Failure | Internal Check | Vigilmon | |---|---|---| | Pomerium process crash | ✓ | ✓ | | TLS certificate expiry | ✗ | ✓ | | Load balancer/ingress misconfiguration | ✗ | ✓ | | Network path blocked | ✗ | ✓ | | Port exhaustion under traffic | ✗ | ✓ |

Step 3: Monitor the Authenticate Service

The authenticate service handles the OIDC login flow — it redirects users to the identity provider, handles the callback, and issues Pomerium session cookies. In split deployments, it runs on its own subdomain (e.g., authenticate.pomerium.example.com).

curl -i https://authenticate.pomerium.example.com/ping
# HTTP/1.1 200 OK
# OK

Configure a second Vigilmon monitor:

  1. URL: https://authenticate.pomerium.example.com/ping
  2. Interval: 1 minute
  3. Expected status: 200
  4. Response body contains: OK
  5. Monitor name: [pomerium-authenticate] /ping
  6. Alert channel: P1 (new logins fail when this is down)

In all-in-one mode, skip this step — the proxy /ping monitor covers the authenticate service.

Distinguishing Proxy vs. Authenticate Failures

Running both monitors lets you separate two different failure scenarios:

  • Proxy down, authenticate up → Routing/network issue at the proxy layer; existing session cookies may still be validated internally
  • Proxy up, authenticate down → New logins fail but existing sessions may continue; the blast radius is narrower

Step 4: Monitor the Authorize Service

The authorize service evaluates access policy for every proxied request. It runs on a gRPC port (5443 by default) but also exposes an HTTP health endpoint at /healthz.

# From internal network (authorize is not internet-facing)
curl -i http://pomerium-authorize.internal:5443/healthz
# HTTP/1.1 200 OK
# {"status":"SERVING"}

If the authorize service is not directly reachable from Vigilmon, expose it through an internal-only load balancer endpoint:

# Nginx internal proxy for authorize health
server {
    listen 8080;
    location /authorize-health {
        proxy_pass http://pomerium-authorize.internal:5443/healthz;
        allow 10.0.0.0/8;
        deny all;
    }
}

Then monitor http://internal-lb.example.com:8080/authorize-health:

  1. Expected status: 200
  2. Response body contains: SERVING
  3. Monitor name: [pomerium-authorize] /healthz

A failure of the authorize service causes Pomerium to fail closed — all requests to protected applications are denied without error messages that reveal the cause.

Step 5: Monitor the Databroker Service

The databroker stores session data, device enrollment state, and directory sync state (when using Google Workspace or Okta directory sync). It also runs on a gRPC port with an HTTP health endpoint:

# From internal network
curl -i http://pomerium-databroker.internal:5443/healthz
# HTTP/1.1 200 OK
# {"status":"SERVING"}

If you use Redis or PostgreSQL as the databroker's storage backend, also monitor those independently:

# Databroker backed by Redis — monitor Redis health
curl -i https://your-app.example.com/health/redis

# Databroker backed by PostgreSQL — monitor PG health
curl -i https://your-app.example.com/health/postgres

Monitor the databroker health endpoint with Vigilmon:

  1. URL: (internal-lb proxied) http://internal-lb.example.com:8080/databroker-health
  2. Expected status: 200
  3. Response body contains: SERVING
  4. Monitor name: [pomerium-databroker] /healthz

When the databroker is down, session verification for existing users fails — people with active sessions start getting logged out, even though the proxy and authenticate services are running.

Step 6: Monitor the Identity Provider Endpoint

Pomerium requires an upstream OIDC identity provider for all authentication. If the IdP becomes unreachable, Pomerium cannot complete new logins. Monitor the IdP's OIDC discovery endpoint separately:

# Google Workspace OIDC
curl -i https://accounts.google.com/.well-known/openid-configuration

# Okta OIDC
curl -i https://your-org.okta.com/.well-known/openid-configuration

# Self-hosted Keycloak
curl -i https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

Add a Vigilmon monitor for your identity provider:

  1. URL: your IdP's OIDC discovery document URL
  2. Interval: 2 minutes
  3. Expected status: 200
  4. Response body contains: "issuer"
  5. Monitor name: [idp] oidc-discovery

Correlating this monitor with the Pomerium authenticate monitor tells you whether a login failure is Pomerium-internal or the IdP's fault.

Step 7: Validate an Authenticated Application Route

The strongest end-to-end check is probing a Pomerium-protected application route that has a known public health endpoint:

# If your protected app exposes /health and Pomerium is configured
# to allow unauthenticated probes to /health
curl -i https://internal-app.example.com/health

Alternatively, configure a Pomerium bypass policy for a specific path in your policy file:

# pomerium policy.yaml
- from: https://internal-app.example.com
  to: http://backend.internal:8080
  routes:
    - path: /health
      allow_public_unauthenticated_access: true

Then monitor https://internal-app.example.com/health with Vigilmon:

  • Expected status: 200
  • Monitor name: [app-via-pomerium] /health

This is the only monitor that proves the full request path — Pomerium proxy → policy evaluation → upstream forwarding — is working end to end.

Step 8: Configure Alert Routing and Escalation

| Monitor | Severity | Alert | |---|---|---| | Proxy /ping | P1 | PagerDuty + Slack immediately | | Authenticate /ping | P1 | PagerDuty + Slack immediately | | Authorize /healthz | P1 | PagerDuty + Slack immediately | | Databroker /healthz | P2 | Slack + email | | IdP OIDC discovery | P2 | Slack + email | | App via Pomerium | P1 | PagerDuty + Slack |

Set confirmation count to 2 on all P1 monitors. Zero-trust enforcement means any of these failures blocks access to your entire internal tooling — page immediately on confirmed outage, not on transient flaps.

Set a response time alert on the proxy monitor at 1000ms. Pomerium adds minimal latency under normal conditions; a slow response may indicate policy evaluation bottlenecks or databroker pressure before it becomes an outage.

Step 9: Build a Pomerium Status Page

Create an internal Vigilmon Status Page for your Pomerium deployment:

  1. Status Pages → New Status Page: Pomerium — Zero Trust Access
  2. Group 1: Public Access Layer — Proxy /ping, App via Pomerium
  3. Group 2: Auth Services — Authenticate /ping, IdP OIDC discovery
  4. Group 3: Internal Services — Authorize /healthz, Databroker /healthz
  5. Visibility: Internal (engineering and security teams only)

This page lets your security and SRE teams immediately locate which layer of the zero-trust stack has failed during an incident.

Summary

Pomerium is the access control boundary for all your internal applications. When it fails, the failure is immediate, broad, and difficult to diagnose without clear monitoring. Vigilmon gives you layered coverage across every service component:

| Monitor | What It Catches | |---|---| | Proxy /ping | Proxy availability, TLS, ingress, network path | | Authenticate /ping | Login flow availability for new sessions | | Authorize /healthz | Policy evaluation service, fail-closed behavior | | Databroker /healthz | Session persistence and directory sync | | IdP OIDC discovery | Upstream identity provider reachability | | App via Pomerium | End-to-end request path through the proxy |

Get started free at vigilmon.online — your first Pomerium monitor is running in under two minutes.

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