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

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.auth.config	stellaops.doctor.auth	fail	auth security core config

Auth Configuration

What It Checks

Validates the overall authentication configuration by inspecting three layers in sequence:

1. Authentication configured -- verifies that the auth subsystem has been set up (issuer URL present, basic config loaded). If not: Fail with "Authentication not configured".
2. Signing keys available -- checks whether signing keys exist for token issuance. If configured but no keys: Fail with "No signing keys available".
3. Signing key expiration -- checks if the active signing key is approaching expiration. If it will expire soon: Warn with the number of days remaining.
4. All healthy -- issuer URL configured, signing keys available, key not near expiry. Result: Pass.

Evidence collected: AuthConfigured (YES/NO), IssuerConfigured (YES/NO), IssuerUrl, SigningKeysConfigured/SigningKeysAvailable (YES/NO), KeyExpiration (days), ActiveClients count, ActiveScopes count.

The check always runs (CanRun returns true).

Why It Matters

Authentication is the foundation of every API call in Stella Ops. If the auth subsystem is not configured, no user can log in, no service-to-service call can authenticate, and the entire platform is non-functional. Missing signing keys mean tokens cannot be issued, and an expiring key that is not rotated will cause a hard outage when it expires.

Common Causes

• Authority service not configured (fresh installation without stella setup auth)
• Missing issuer URL configuration in environment variables or config files
• Signing keys not yet generated (first-run setup incomplete)
• Key material corrupted (disk failure, accidental deletion)
• HSM/PKCS#11 module not accessible (hardware key store offline)
• Signing key approaching expiration without scheduled rotation

How to Fix

Docker Compose

# Check Authority service configuration
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
  cat /app/appsettings.json | grep -A5 "Issuer\|Signing"

# Set issuer URL via environment variable
# In .env or docker-compose.override.yml:
# AUTHORITY__ISSUER__URL=https://stella-ops.local/authority

# Restart Authority service after config changes
docker compose -f devops/compose/docker-compose.stella-ops.yml restart authority

# Generate signing keys
docker compose -f devops/compose/docker-compose.stella-ops.yml exec authority \
  stella keys generate --type rsa

Bare Metal / systemd

# Run initial auth setup
stella setup auth

# Configure issuer URL
stella auth configure --issuer https://auth.yourdomain.com

# Generate signing keys
stella keys generate --type rsa

# Rotate signing keys (if approaching expiration)
stella keys rotate

# Schedule automatic key rotation
stella keys rotate --schedule 30d

# Check key store health
stella doctor run --check check.crypto.keystore

Kubernetes / Helm

# Check authority pod configuration
kubectl get configmap stellaops-authority-config -n stellaops -o yaml

# Set issuer URL in Helm values
# authority:
#   issuer:
#     url: "https://auth.yourdomain.com"
helm upgrade stellaops stellaops/stellaops -f values.yaml

# Generate keys via job
kubectl exec -it deploy/stellaops-authority -n stellaops -- \
  stella keys generate --type rsa

# Check secrets for key material
kubectl get secret stellaops-signing-keys -n stellaops

Verification

stella doctor run --check check.auth.config

Related Checks

• check.auth.signing-key -- deeper signing key health (algorithm, size, rotation schedule)
• check.auth.token-service -- verifies token endpoint is responsive
• check.auth.oidc -- external OIDC provider connectivity