tutorial

How to Monitor Casdoor with Vigilmon

Casdoor is the identity and access management layer for your applications — when its web UI or API goes down, logins fail for every connected app. Here's how to monitor Casdoor availability, API health, OIDC discovery, and provider connectivity with Vigilmon.

Casdoor is an open-source identity and access management platform that provides single sign-on, OAuth2/OIDC, SAML, and social login for your applications. It hosts your login pages, manages user sessions, and acts as the OIDC provider that your applications trust. When Casdoor is unavailable — whether due to a database issue, a crashed process, or a misconfigured identity provider — every application that delegates authentication to it stops accepting new logins.

Vigilmon gives you external visibility into Casdoor's web UI availability, API health, OIDC discovery endpoint, and upstream identity provider connectivity. This tutorial walks through building comprehensive monitoring for a self-hosted Casdoor deployment.

Why Monitoring Casdoor Matters

Casdoor's role as an IAM platform means its failures are multiplied across every connected application:

  • Web UI unavailability — the login page your users land on returns a 502 or timeout; they cannot authenticate regardless of their credentials
  • API failures — programmatic user management, role assignment, and application registration all break silently
  • OIDC discovery endpoint failure — applications configured with OIDC auto-discovery cannot initialize their auth libraries on startup or after cache expiry
  • Social provider outages — if a configured Google, GitHub, or LDAP provider becomes unreachable, users relying on those login methods are locked out even though Casdoor itself is running
  • Database connectivity loss — Casdoor stores user accounts, application registrations, and sessions; a database failure prevents all login and account management operations

Internal process monitoring confirms the Go binary is running. External monitoring with Vigilmon confirms the full authentication path is working from the perspective of your users and applications.

Step 1: Identify Casdoor's Key Endpoints

By default, Casdoor runs on port 8000 (HTTP) or behind a TLS-terminating reverse proxy. Its primary endpoints for monitoring are:

| Endpoint | Purpose | |---|---| | / (web UI root) | Main login interface | | /api/health | API health check | | /.well-known/openid-configuration | OIDC discovery document | | /api/get-organizations | API functionality check |

Verify your Casdoor installation is accessible:

# Confirm web UI is live
curl -i https://auth.example.com/
# HTTP/2 200

# Confirm OIDC discovery
curl -i https://auth.example.com/.well-known/openid-configuration
# HTTP/2 200
# {"issuer":"https://auth.example.com",...}

Step 2: Monitor the Web UI Availability

The web UI is the login page your users see. Monitoring it confirms that Casdoor's frontend is rendering and that your reverse proxy, TLS termination, and underlying Go server are all working.

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to: https://auth.example.com/
  4. Set the check interval to 1 minute
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: Casdoor (or a string from your customized login page)
    • Response time threshold: 2000ms
  6. Set the monitor name: [casdoor] web UI
  7. Assign your primary alert channel
  8. Save

Because the login page renders server-side HTML, a 200 with the expected string confirms the entire web serving stack — not just a static file.

What the Web UI Monitor Catches

| Failure | Process Monitor | Vigilmon | |---|---|---| | Casdoor process crash | ✓ | ✓ | | Nginx/Caddy reverse proxy misconfiguration | ✗ | ✓ | | TLS certificate expiry | ✗ | ✓ | | Database connectivity loss (page fails to render) | ✗ | ✓ | | OOM kill during login page rendering | ✗ | ✓ |

Step 3: Monitor the API Health Endpoint

Casdoor exposes an API health endpoint that returns the status of the server:

curl -i https://auth.example.com/api/health
# HTTP/2 200
# {"status":"ok"}

If this endpoint returns an error or is unreachable, programmatic interactions (user provisioning, SCIM sync, application registration via API) are failing. This monitor is distinct from the web UI monitor — it specifically validates the API layer.

Configure a Vigilmon HTTP monitor:

  1. URL: https://auth.example.com/api/health
  2. Interval: 1 minute
  3. Expected status: 200
  4. Response body contains: "ok" or "status"
  5. Monitor name: [casdoor] /api/health

Step 4: Monitor the OIDC Discovery Endpoint

Applications configured to use Casdoor as an OIDC provider call the discovery endpoint at startup to find the authorization, token, and JWKS URLs. If this endpoint is unavailable, applications cannot initialize their OIDC clients.

curl -i https://auth.example.com/.well-known/openid-configuration
# HTTP/2 200
# {"issuer":"https://auth.example.com","authorization_endpoint":"...","token_endpoint":"...","jwks_uri":"..."}

Add a Vigilmon monitor:

  1. URL: https://auth.example.com/.well-known/openid-configuration
  2. Interval: 2 minutes
  3. Expected status: 200
  4. Response body contains: "issuer"
  5. Monitor name: [casdoor] oidc-discovery

The discovery document includes the jwks_uri which tells OIDC clients where to fetch public keys. Additionally, monitor the JWKS URI directly:

curl -i https://auth.example.com/.well-known/jwks
# HTTP/2 200
# {"keys":[...]}

Add a separate monitor:

  1. URL: https://auth.example.com/.well-known/jwks
  2. Interval: 5 minutes
  3. Response body contains: "keys"
  4. Monitor name: [casdoor] /jwks

Step 5: Monitor Provider Connectivity

Casdoor typically federates multiple identity providers — Google, GitHub, Microsoft, LDAP, and custom OIDC providers. If a provider is unreachable, users who authenticate through that provider are locked out. You can monitor the reachability of external providers separately to distinguish Casdoor-internal failures from provider-side failures:

Monitor Social Providers

For each social provider you have configured:

# Check Google's OIDC discovery (used for Google sign-in)
curl -i https://accounts.google.com/.well-known/openid-configuration

# Check GitHub OAuth endpoint
curl -i https://github.com/login/oauth/authorize

Add lightweight Vigilmon monitors for each:

  1. Google OIDC: https://accounts.google.com/.well-known/openid-configuration, interval 5 min
  2. GitHub OAuth: https://api.github.com/, interval 5 min (GitHub API availability)
  3. Microsoft: https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration, interval 5 min

When users report login failures, correlating the Casdoor monitors with the provider monitors immediately tells you whether the issue is Casdoor itself or an upstream provider.

Monitor Internal LDAP/AD (if applicable)

If you use Casdoor with LDAP or Active Directory, add a TCP port monitor for the LDAP endpoint:

  1. Monitor type: TCP
  2. Host: ldap.internal.example.com
  3. Port: 389 (or 636 for LDAPS)
  4. Monitor name: [ldap] connectivity

Step 6: Create a Synthetic Login Flow Check

For the highest-confidence monitoring, create a health endpoint in your Casdoor application layer that performs an actual OAuth2 client credentials flow and returns the result:

# casdoor_healthcheck.py — FastAPI health endpoint
import httpx
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

CASDOOR_URL = "https://auth.example.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"

@app.get("/health/casdoor")
async def casdoor_health():
    try:
        async with httpx.AsyncClient(timeout=5.0) as client:
            # Fetch OIDC discovery
            disc = await client.get(f"{CASDOOR_URL}/.well-known/openid-configuration")
            disc.raise_for_status()
            token_endpoint = disc.json()["token_endpoint"]

            # Request a client credentials token
            token_resp = await client.post(token_endpoint, data={
                "grant_type": "client_credentials",
                "client_id": CLIENT_ID,
                "client_secret": CLIENT_SECRET,
            })
            token_resp.raise_for_status()

        return {"status": "ok", "token_endpoint": token_endpoint}
    except Exception as e:
        return JSONResponse(status_code=503, content={"status": "down", "error": str(e)})

Monitor https://your-app.example.com/health/casdoor with Vigilmon:

  • Expected status: 200
  • Response body contains: "ok"
  • Monitor name: [casdoor] synthetic-login

This end-to-end check catches misconfigured client secrets, revoked application registrations, and token issuance failures that the simpler endpoint monitors would miss.

Step 7: Configure Alert Routing

| Monitor | Severity | Alert | |---|---|---| | Web UI (/) | P1 | PagerDuty + Slack | | /api/health | P1 | PagerDuty + Slack | | OIDC discovery | P1 | PagerDuty + Slack | | JWKS endpoint | P2 | Slack + email | | Provider monitors | P2 | Slack (for provider-specific outages) | | Synthetic login | P1 | PagerDuty + Slack |

Set confirmation count to 2 on P1 monitors to avoid paging on transient probe failures while still alerting within 2 minutes of a confirmed outage.

Summary

Casdoor centralizes authentication for every application in your stack. Vigilmon gives you layered coverage from the frontend to the OIDC protocol layer:

| Monitor | What It Catches | |---|---| | Web UI availability | Login page rendering, reverse proxy, TLS | | /api/health | API layer and database connectivity | | OIDC discovery | OIDC client initialization, protocol availability | | JWKS endpoint | JWT validation key availability | | Provider monitors | Upstream social/LDAP provider failures | | Synthetic login | End-to-end token issuance |

Get started free at vigilmon.online — your first Casdoor 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