git.stella-ops.org/docs/doctor/articles/auth/oidc.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.auth.oidc	stellaops.doctor.auth	warn	auth oidc connectivity

OIDC Provider Connectivity

What It Checks

Tests connectivity to an external OIDC provider by performing real HTTP requests. The check reads the issuer URL from configuration keys (in priority order): Authentication:Oidc:Issuer, Auth:Oidc:Authority, Oidc:Issuer. If none is configured, the check passes immediately (local authority mode).

When an external provider is configured, the check performs a multi-step validation:

1. Fetch discovery document -- HTTP GET to {issuerUrl}/.well-known/openid-configuration with a 10-second timeout. If unreachable: Fail with connection error type classification (ssl_error, dns_failure, refused, timeout, connection_failed).
2. Validate discovery fields -- Parses the discovery JSON and verifies presence of authorization_endpoint, token_endpoint, and jwks_uri. If any are missing: Warn listing the missing fields.
3. Fetch JWKS -- HTTP GET to the jwks_uri from the discovery document. Counts the number of keys in the keys array. If zero keys: Warn (token validation may fail).
4. All healthy -- provider reachable, discovery valid, JWKS has keys. Result: Pass.

Evidence collected: issuer_url, discovery_reachable, discovery_response_ms, authorization_endpoint_present, token_endpoint_present, jwks_uri_present, jwks_key_count, jwks_fetch_ms, http_status_code, error_message, connection_error_type.

Why It Matters

When Stella Ops is configured to delegate authentication to an external OIDC provider (Azure AD, Keycloak, Okta, etc.), all user logins and token validations depend on that provider being reachable and correctly configured. A connectivity failure means users cannot log in, and services cannot validate tokens, leading to a platform-wide authentication outage.

Common Causes

• OIDC provider is down or undergoing maintenance
• Network connectivity issue (proxy misconfiguration, firewall rule change)
• DNS resolution failure for the provider hostname
• Firewall blocking outbound HTTPS to the provider
• Discovery document missing required fields (misconfigured provider)
• Token endpoint misconfigured after provider upgrade
• JWKS endpoint returning empty key set (key rotation in progress)
• OIDC provider rate limiting or returning errors

How to Fix

Docker Compose

# Test OIDC provider connectivity from the authority container
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
  curl -s https://<oidc-issuer>/.well-known/openid-configuration | jq .

# Check DNS resolution
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
  nslookup <oidc-host>

# Set OIDC configuration via environment
# AUTHENTICATION__OIDC__ISSUER=https://login.microsoftonline.com/<tenant>/v2.0

Bare Metal / systemd

# Test provider connectivity
curl -s https://<oidc-issuer>/.well-known/openid-configuration | jq .

# Check DNS resolution
nslookup <oidc-host>

# Validate OIDC configuration
stella auth oidc validate

# Check JWKS endpoint
curl -s $(curl -s https://<oidc-issuer>/.well-known/openid-configuration | jq -r .jwks_uri) | jq .

# Check network connectivity
stella doctor run --check check.network.dns

Kubernetes / Helm

# Test from authority pod
kubectl exec -it deploy/stellaops-authority -n stellaops -- \
  curl -s https://<oidc-issuer>/.well-known/openid-configuration | jq .

# Check NetworkPolicy allows egress to OIDC provider
kubectl get networkpolicy -n stellaops -o yaml | grep -A10 egress

# Set OIDC configuration in Helm values
# authority:
#   oidc:
#     issuer: "https://login.microsoftonline.com/<tenant>/v2.0"
helm upgrade stellaops stellaops/stellaops -f values.yaml

Verification

stella doctor run --check check.auth.oidc

Related Checks

• check.auth.config -- overall auth configuration health
• check.auth.signing-key -- local signing key health (used when not delegating to external OIDC)
• check.auth.token-service -- token endpoint availability