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>
This commit is contained in:
75
docs/doctor/articles/integration/oidc-provider.md
Normal file
75
docs/doctor/articles/integration/oidc-provider.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
checkId: check.integration.oidc
|
||||
plugin: stellaops.doctor.integration
|
||||
severity: warn
|
||||
tags: [connectivity, oidc, auth, identity]
|
||||
---
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# values.yaml
|
||||
oidc:
|
||||
issuer: https://auth.example.com
|
||||
clientId: stellaops-ui
|
||||
```
|
||||
```bash
|
||||
helm upgrade stellaops ./chart -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.integration.oidc
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.integration.ldap` -- alternative directory-based authentication
|
||||
Reference in New Issue
Block a user