Monitoring ZITADEL with Vigilmon: Health Endpoint, OIDC Discovery, Login UI, gRPC Port & SSL Alerts

ZITADEL is a modern identity and access management platform — providing OpenID Connect, OAuth2, SAML, and passkey authentication for your applications. When ZITADEL goes down, every application that delegates authentication to it stops working for users. Login pages fail, API tokens can't be issued, and downstream authorization checks return errors. Vigilmon gives you external visibility into ZITADEL's health: the built-in health endpoint, OIDC discovery document, login UI availability, gRPC port connectivity, and SSL certificate expiry — so you detect auth failures before your users do.

What You'll Build

• A monitor on ZITADEL's /debug/healthz health endpoint for server availability
• An OIDC discovery check to confirm the identity layer is functioning
• A login UI availability monitor to catch frontend failures
• A gRPC port TCP monitor for API connectivity
• SSL certificate monitoring for your ZITADEL domain
• An alerting setup that distinguishes server-level failures from UI or API degradation

Prerequisites

• A running ZITADEL 2.x instance with a public or network-reachable domain
• HTTPS configured (e.g., https://auth.example.com)
• A free account at vigilmon.online

Step 1: Verify ZITADEL's Health Endpoints

ZITADEL exposes two health endpoints:

• /debug/healthz — basic liveness check; confirms the process is running
• /debug/ready — readiness check; confirms the database connection and gRPC layer are initialized

curl https://auth.example.com/debug/healthz

A healthy ZITADEL returns:

{}

(An empty JSON object with HTTP 200.)

curl https://auth.example.com/debug/ready

A ready ZITADEL returns:

{}

If /debug/ready returns a non-200 status or a body indicating dependency failures, ZITADEL is not ready to serve authentication requests — the database may be unreachable or a required service hasn't initialized.

Version note: In ZITADEL versions before 2.x, the health endpoint may be at /healthz. Check your ZITADEL documentation for the version you're running.

Step 2: Create a Vigilmon HTTP Monitor for the Readiness Endpoint

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://auth.example.com/debug/ready.
3. Check interval: 60 seconds.
4. Response timeout: 15 seconds.
5. Expected status: 200.
6. Keyword: {} (the body returned by a healthy ready endpoint — adjust if your version returns a richer body).
7. Click Save.

This monitor fires when:

• The ZITADEL process crashes or is OOM-killed
• The database (CockroachDB or PostgreSQL) becomes unreachable
• A deployment fails to complete initialization
• The host becomes unreachable

Alert sensitivity: Set to trigger after 1 consecutive failure. A down ZITADEL server means authentication fails for every application using it.

Step 3: Monitor the OIDC Discovery Endpoint

ZITADEL serves an OpenID Connect discovery document at /.well-known/openid-configuration. This document is the entry point that all OIDC clients use to find token endpoints, JWKS URIs, and authorization endpoints. If the discovery document is unavailable or malformed, every OIDC client fails to initialize:

curl https://auth.example.com/.well-known/openid-configuration

A healthy ZITADEL returns a JSON document containing:

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/v2/authorize",
  "token_endpoint": "https://auth.example.com/oauth/v2/token",
  "jwks_uri": "https://auth.example.com/oauth/v2/keys",
  ...
}

Add a Vigilmon monitor for the OIDC discovery endpoint:

1. Add Monitor → HTTP.
2. URL: https://auth.example.com/.well-known/openid-configuration.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Keyword: token_endpoint (always present in a valid OIDC discovery document).
6. Label: ZITADEL OIDC discovery.
7. Click Save.

When the readiness monitor is green but the OIDC discovery monitor fires, you have an OIDC layer issue — possibly a misconfigured domain, a TLS termination problem, or a routing issue at the reverse proxy.

Step 4: Monitor the Login UI

ZITADEL's login UI is the page users see when they authenticate. A broken login UI means users cannot log in even if the OIDC API layer is healthy. The login UI involves additional JavaScript, templating, and static asset serving:

curl https://auth.example.com/login

1. Add Monitor → HTTP.
2. URL: https://auth.example.com/login (or your ZITADEL instance's login URL — this may vary by custom domain configuration).
3. Check interval: 5 minutes.
4. Expected status: 200.
5. Keyword: ZITADEL (appears in the login page HTML; adjust to a string that appears on your ZITADEL login page, such as your instance name or Sign in).
6. Label: ZITADEL Login UI.
7. Click Save.

Custom branding: If you've customized ZITADEL's login UI with your own branding, the default ZITADEL keyword may not appear. Use a keyword from your custom login page — such as your company name, a heading like Sign in, or a specific CSS class name that's always rendered.

Step 5: Monitor the gRPC API Port

ZITADEL exposes its management and admin APIs over gRPC (default port 8080 for HTTP/2 gRPC, or the same port as HTTPS when using gRPC-over-TLS). Many ZITADEL integrations — including the Terraform provider, management API clients, and custom SDKs — use gRPC directly. When the gRPC listener is unavailable, API-driven operations fail even if the web UI and OIDC endpoints appear healthy.

Check TCP connectivity to the gRPC port:

1. Add Monitor → TCP Port.
2. Host: auth.example.com.
3. Port: 443 (if ZITADEL serves gRPC on the same HTTPS port, which is the default for cloud and self-hosted deployments) or 8080 (if using a separate gRPC listener).
4. Check interval: 2 minutes.
5. Label: ZITADEL gRPC port.
6. Click Save.

Port configuration: Check your ZITADEL configuration (ExternalPort, TLS.Enabled) to confirm which port gRPC traffic uses. Most single-port deployments serve both HTTPS and gRPC on port 443 via HTTP/2.

Step 6: Monitor SSL Certificates

ZITADEL's SSL certificate protects every channel: the web UI, the OIDC token and authorization endpoints, the JWKS URI, and the gRPC API. An expired certificate causes all OIDC clients to fail token validation, all management API calls to fail TLS handshakes, and users to see browser certificate errors:

1. Add Monitor → SSL Certificate.
2. Domain: auth.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

JWKS key rotation: ZITADEL rotates its signing keys independently of the SSL certificate. While Vigilmon monitors the TLS certificate on the endpoint, keep an eye on key rotation schedules in the ZITADEL admin console to avoid token validation failures caused by stale JWKS caches in your applications.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | /debug/ready | Non-200 or empty body missing | Check ZITADEL process; verify database (CockroachDB/Postgres) connectivity; review logs | | OIDC discovery | Non-200 or token_endpoint missing | Check reverse proxy routing; verify ZITADEL HTTP listener; inspect TLS termination | | Login UI | Non-200 or keyword missing | Check static asset serving and templating; review ZITADEL logs for rendering errors | | gRPC TCP port | Connection refused or timeout | Check gRPC listener config; verify firewall rules on the gRPC port | | SSL certificate | < 30 days to expiry | Renew certificate; check ACME automation or cert manager |

Alert after: 1 consecutive failure for readiness, OIDC, and SSL monitors; 2 consecutive failures for gRPC TCP and login UI (transient during rolling restarts).

Common ZITADEL Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | ZITADEL process crash or OOM | /debug/ready unreachable; alert within 60 s | | Database goes down | /debug/ready returns non-200; all auth requests fail | | OIDC discovery broken (proxy misconfiguration) | OIDC monitor fires; readiness may stay green | | Login UI rendering failure | Login UI monitor fires; OIDC API still healthy | | gRPC port blocked by firewall | gRPC TCP monitor fires; REST and UI may still work | | SSL certificate expires | SSL monitor alerts at 30-day threshold; all clients fail TLS | | DNS misconfiguration | All monitors fire simultaneously | | Signing key rotation issue | Tokens fail validation; OIDC discovery may still return 200 |

ZITADEL is the authentication layer that gates every user's access to your applications — when it fails, the impact is immediate and broad. A down readiness endpoint means no logins; a broken OIDC discovery document means no new clients can initialize; an expired SSL certificate means all channels fail at once. Vigilmon gives you layered external monitoring of ZITADEL's health, OIDC availability, login UI, gRPC connectivity, and SSL certificates so you detect auth failures the moment they happen.

Start monitoring ZITADEL in under 5 minutes — register free at vigilmon.online.