Files

master c58a236d70 Doctor plugin checks: implement health check classes and documentation

Implement remediation-aware health checks across all Doctor plugin modules
(Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment,
EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release,
Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation,
Authority, Core, Cryptography, Database, Docker, Integration, Notify,
Observability, Security, ServiceGraph, Sources, Verification).

Each check now emits structured remediation metadata (severity, category,
runbook links, and fix suggestions) consumed by the Doctor dashboard
remediation panel.

Also adds:
- docs/doctor/articles/ knowledge base for check explanations
- Advisory AI search seed and allowlist updates for doctor content
- Sprint plan for doctor checks documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-27 12:28:00 +02:00

2.6 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

OIDC Provider

What It Checks

Reads the OIDC issuer URL from Oidc:Issuer, Authentication:Oidc:Issuer, or Authority:Oidc:Issuer. Fetches the OpenID Connect discovery document at <issuer>/.well-known/openid-configuration. On a successful response, parses the JSON for three required endpoints: authorization_endpoint, token_endpoint, and jwks_uri. The check passes if all three are present, warns if the discovery document is incomplete (missing one or more endpoints), fails if the discovery endpoint returns a non-success status code, and fails on connection errors.

Why It Matters

OIDC authentication is the primary identity mechanism for Stella Ops operators and API clients. If the OIDC provider is unreachable or misconfigured, users cannot log in, API tokens cannot be validated, and all authenticated workflows halt. An incomplete discovery document causes subtle failures where some auth flows work but others (e.g., token refresh) silently break.

Common Causes

OIDC issuer URL is incorrect or has a trailing slash issue
OIDC provider (Authority, Keycloak, Azure AD, etc.) is down
Network connectivity issues between Stella Ops and the identity provider
Provider does not support OpenID Connect discovery
Discovery document is missing required endpoints

How to Fix

Docker Compose

# Check OIDC configuration
grep 'OIDC__ISSUER\|AUTHENTICATION__OIDC' .env

# Test discovery endpoint
docker compose exec gateway curl -sv \
  https://auth.example.com/.well-known/openid-configuration

# Verify the Authority service is running
docker compose ps authority

# Update issuer URL
echo 'Oidc__Issuer=https://auth.example.com' >> .env
docker compose restart gateway platform

Bare Metal / systemd

# Verify configuration
cat /etc/stellaops/appsettings.Production.json | jq '.Oidc'

# Test discovery
curl -v https://auth.example.com/.well-known/openid-configuration

# Check required fields in the response
curl -s https://auth.example.com/.well-known/openid-configuration \
  | jq '{authorization_endpoint, token_endpoint, jwks_uri}'

# Fix configuration
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oidc:
  issuer: https://auth.example.com
  clientId: stellaops-ui

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor run --check check.integration.oidc

check.integration.ldap -- alternative directory-based authentication

2.6 KiB Raw Blame History