checkId: check.integration.oidc plugin: stellaops.doctor.integration severity: warn tags: [connectivity, oidc, auth, identity]

OIDC Provider

This Doctor check verifies that the Stella Ops control plane can reach its configured OpenID Connect provider and that the provider advertises a complete discovery document. It is aimed at operators and DevOps engineers diagnosing operator sign-in and API-token validation problems.

What It Checks

Reads the OIDC issuer URL from Oidc:Issuer, Authentication:Oidc:Issuer, or Authority:Oidc:Issuer. For cataloged tenants, tenant overrides under Doctor:TenantOverrides:<tenant>:<key> or Tenants:<tenant>:<key> are checked before the global keys. 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.

Transient discovery fetch exceptions are retried with bounded ProbeRetry; incomplete or non-success discovery responses are returned immediately. Evidence records per-tenant status and retry attempts when tenant fan-out is active.

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

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 --check check.integration.oidc