EQTY LabDocs

Auth Service Operations

Health checks, identity provider issues, and operational troubleshooting for Auth Service.

View as Markdown

Auth Service issues usually appear as sign-in failures, authorization failures, missing membership, API key problems, service-account failures, or signing failures.

Health Checks

/health is liveness only and /health/ready pings the database. /health/auth fetches the identity provider’s JWKS and /health/signing checks OpenBao without signing; both require the Auth Service API secret (API_SECRET) as a bearer token:

bash
curl https://guardian.example.com/authService/health
curl https://guardian.example.com/authService/health/ready
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/auth
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/signing

A ready response:

json
{
  "status": "ready",
  "service": "auth-service",
  "database": "ok",
  "timestamp": "2026-10-16T12:00:00Z",
  "version": "1.2.1"
}

/health/ready and /health/auth return 503 with "status": "not_ready" when the database or identity provider is unreachable, and 401 on the authenticated probes for a missing or wrong secret. /health/signing returns 200 only for ready, or not_supported when the key-management provider is not OpenBao; uninitialized, sealed, denied, unreachable, timeout, canceled, association_mismatch, and unavailable return 503.

First Checks

  • Confirm Auth Service is running and ready.
  • Confirm it can reach the configured identity provider.
  • Confirm platform services are configured to trust the same Auth Service.
  • Confirm the user or integration has the expected membership and role.
  • Confirm key-management access is available when signing workflows fail.

Common Symptoms

  • User can sign in but cannot open a project: check project membership.
  • User cannot perform an action: check role permissions for the current project.
  • API key fails: check whether the key was revoked, rotated, scoped differently than expected, or limited by allowedIps to other addresses.
  • Service account fails: check operator-managed service-account configuration and secrets.
  • Token exchange fails: confirm the deployment uses Keycloak or Microsoft Entra.

Escalation Information

When escalating, include provider mode, affected user or service account, approximate time, impacted project, and the action that failed. Do not include raw tokens, API keys, or private key material.