tutorial

How to Monitor Kanidm with Vigilmon (LDAP, HTTPS, OAuth2, and Replication Health)

Kanidm is a modern, Rust-based identity management server designed for security and correctness from the ground up. It replaces aging LDAP directories and OA...

Kanidm is a modern, Rust-based identity management server designed for security and correctness from the ground up. It replaces aging LDAP directories and OAuth2 providers with a single, opinionated platform that handles authentication, authorization, and group management for your entire self-hosted infrastructure. But when Kanidm goes down — or quietly starts returning errors — every service that delegates authentication to it goes dark at the same time.

In this tutorial you'll set up end-to-end monitoring for Kanidm using Vigilmon — free tier, no credit card required.

Why Kanidm needs dedicated monitoring

Kanidm is the authentication backbone for everything it protects. A failure here is never isolated:

  • Cascading authentication failures — when Kanidm's HTTPS API goes unreachable, every app using its OAuth2 or LDAP provider fails login simultaneously
  • Silent replication lag — in a multi-node setup, a replica can fall behind without any visible error, causing split-brain authentication decisions
  • OAuth2 token endpoint degradation — the /oauth2/token endpoint can return errors or slow responses that break CI/CD pipelines and API-driven services before users notice
  • LDAP port saturation — legacy apps bound to Kanidm's LDAP interface can exhaust connection pools, producing intermittent authentication failures that are hard to trace
  • Certificate expiry — Kanidm is strict about TLS. An expired certificate will hard-block all client connections without a graceful fallback

External monitoring from a neutral vantage point is the only way to know Kanidm is working as your users and services actually experience it.

What you'll need

  • A running Kanidm server (self-hosted, version 1.1.0 or later)
  • A free Vigilmon account (sign-up takes 30 seconds)
  • Your Kanidm server's public hostname and port (default HTTPS: 8443, LDAP: 3636)

Step 1: Verify your Kanidm health endpoint

Kanidm exposes a built-in health endpoint at /status. This endpoint returns HTTP 200 when the server is operational and accepting requests.

Test it from your server:

curl -sf https://your-kanidm.example.com:8443/status
# {"version":"kanidm 1.1.0","healthy":true}

If you're using a reverse proxy (nginx, Caddy, Traefik) to terminate TLS on port 443, test that path too:

curl -sf https://your-kanidm.example.com/status

The /status endpoint does not require authentication, making it safe to poll externally without exposing credentials.

Step 2: Set up HTTPS health monitoring in Vigilmon

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS as the monitor type
  3. Set the URL to your Kanidm status endpoint: https://your-kanidm.example.com/status
  4. Set the check interval to 1 minute
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: "healthy":true
  6. Save the monitor

Vigilmon will now probe your Kanidm status endpoint from multiple regions every minute. If it returns anything other than 200 — or if "healthy":true is absent — an incident opens immediately.

Step 3: Monitor the OAuth2 token endpoint

Your OAuth2 clients don't care whether /status is healthy — they care whether /oauth2/token responds correctly. Add a separate monitor targeting the OAuth2 discovery document, which should always return metadata even without credentials:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to: https://your-kanidm.example.com/oauth2/openid/{your-client-id}/.well-known/openid-configuration
  4. Set the check interval to 2 minutes
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: "token_endpoint"
  6. Save the monitor

If this endpoint stops returning valid JSON or begins returning 5xx errors, Vigilmon fires an alert before your users hit failed logins.

Step 4: Add TCP monitoring for the LDAP port

Applications using Kanidm's LDAP interface connect on port 3636 (LDAPS). HTTP checks won't catch a situation where the HTTPS API is healthy but the LDAP listener has crashed or is unreachable.

  1. In Vigilmon, go to Monitors → New Monitor
  2. Choose TCP Port
  3. Enter your server hostname: your-kanidm.example.com
  4. Enter port: 3636
  5. Set check interval to 1 minute
  6. Save the monitor

This gives you an independent signal for the LDAP subsystem, separate from HTTPS availability.

Step 5: Monitor replication health (multi-node setups)

If you run Kanidm in a replicated configuration, each replica exposes its own /status endpoint. A replica that falls behind won't surface errors to users immediately — they'll get stale data or inconsistent authentication decisions.

Add a separate HTTP monitor for each replica node:

| Monitor name | URL | |---|---| | Kanidm Primary | https://kanidm-primary.example.com/status | | Kanidm Replica 1 | https://kanidm-replica1.example.com/status | | Kanidm Replica 2 | https://kanidm-replica2.example.com/status |

When any replica node goes down, you'll know which one before it affects clients that happen to connect to it.

Step 6: Configure SSL certificate monitoring

Kanidm is strict about TLS — an expired certificate causes hard failures across all clients with no graceful degradation. Vigilmon's SSL monitoring alerts you before expiry.

  1. Go to Monitors → New Monitor
  2. Choose SSL Certificate
  3. Enter your Kanidm domain: your-kanidm.example.com
  4. Set expiry warning threshold to 30 days
  5. Save the monitor

You'll receive an alert 30 days before expiry, giving you time to renew without a midnight scramble.

Step 7: Set up alert channels

When Kanidm goes down, you need to know in seconds — not when a user reports a login failure. Vigilmon supports multiple alert delivery channels.

Webhook (Slack, Discord, PagerDuty):

  1. Go to Alert Channels → Add Channel → Webhook
  2. Enter your webhook URL
  3. Assign the channel to all your Kanidm monitors

Email alerts:

  1. Go to Alert Channels → Add Channel → Email
  2. Enter the on-call email address
  3. Assign to monitors

Example payload Vigilmon sends when Kanidm's health endpoint goes down:

{
  "monitor_name": "Kanidm /status",
  "status": "down",
  "url": "https://your-kanidm.example.com/status",
  "started_at": "2026-01-15T02:14:00Z",
  "duration_seconds": 63
}

Step 8: Create a status page for your identity infrastructure

A public (or internal) status page gives your team a single URL to check when they suspect authentication issues.

  1. In Vigilmon, go to Status Pages → New Status Page
  2. Name it "Identity Infrastructure" or similar
  3. Add all your Kanidm monitors: HTTPS health, OAuth2 discovery, LDAP TCP, SSL cert, and any replica nodes
  4. Publish the page

Share the link in your team's runbook so the first question — "is it Kanidm?" — can be answered in one click.

Recommended monitor summary

| Monitor | Type | Checks for | |---|---|---| | https://your-kanidm/status | HTTP | Server availability, overall health | | https://your-kanidm/oauth2/openid/{client}/.well-known/openid-configuration | HTTP | OAuth2 provider health | | your-kanidm:3636 | TCP | LDAP listener availability | | your-kanidm.example.com | SSL | Certificate expiry | | Replica node /status (repeat per replica) | HTTP | Replication node health |

What's next

  • Heartbeat monitoring — if you run Kanidm backup jobs or replication sync scripts, add a Vigilmon heartbeat monitor so you know when the scheduled job stops running
  • Response time tracking — Vigilmon logs response times for every check; watch for latency spikes on the /oauth2/token endpoint that indicate load or database pressure before they cause timeouts

Get started free at vigilmon.online — no credit card, monitors are live in under a minute.

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