---
checkId: check.auth.config
plugin: stellaops.doctor.auth
severity: fail
tags: [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

```bash
# 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

```bash
# 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

```bash
# 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