Authentication can fail even when an identity provider is online. A changed issuer, missing authorization endpoint, stale signing-key URL, or unsupported response mode in an OpenID Connect discovery document can break every new sign-in while ordinary uptime checks still return HTTP 200. A scheduled web cron job can validate this metadata contract before users discover the regression.
What the discovery document controls
OpenID Connect clients obtain provider metadata from a well-known JSON document. It advertises the issuer, authorization endpoint, token endpoint, JSON Web Key Set location, supported scopes, response types, grant types, signing algorithms, and optional capabilities such as revocation or user information. Client libraries often cache these values, so a bad deployment may create delayed or inconsistent failures.
The monitor should fetch the same public discovery URL used by production clients and compare a small set of required fields against an approved baseline. This complements scheduled API health checks because it verifies configuration semantics, not just reachability.
Define a safe metadata contract
Start with invariants rather than a byte-for-byte copy. JSON member order and optional capabilities can change harmlessly, while a single issuer mismatch is critical. Record the exact issuer, required HTTPS endpoints, expected hostnames, mandatory grant and response types, and accepted signing algorithms.
- The response must be HTTP 200 with a JSON content type.
- The issuer must exactly match the configured issuer, including path and trailing-slash rules.
- Authorization, token, user-info, revocation, and JWKS endpoints must use HTTPS and approved hosts.
- Required scopes and grant types must remain available.
- Weak or unexpected signing algorithms must trigger an alert.
- The response must arrive within a defined latency budget.
Validate the document structure
A successful fetch is only the first step. Parse the response as JSON, reject duplicate or malformed values, and check that every required property has the expected type. URL fields should be absolute HTTPS URLs. Arrays should contain the capabilities your application actually depends on. Ignore unfamiliar optional members unless policy requires an allowlist; this prevents harmless provider improvements from producing noise.
Check the signing-key endpoint
Discovery metadata normally points to a JWKS document containing public signing keys. Schedule a second read-only request to that URL. Confirm that it returns valid JSON, at least one usable signing key, unique key IDs, supported key types, and reasonable cache headers. Do not alert simply because a provider rotates keys; rotations are expected. Alert when the set becomes empty, malformed, unreachable, or incompatible with the algorithms your clients accept.
Key checks should never log full tokens or private credentials. The monitor only needs public metadata. Follow the same defensive approach described in securing web cron endpoints.
Watch redirects, certificates, and caches
A redirect can move discovery traffic to an unexpected host or downgrade a secure route. Record the final URL and fail when it leaves the approved identity domain. Verify certificate validity and hostname matching. If a CDN serves the document, compare cache headers and occasionally test from more than one region to catch stale edge configurations.
Security-header changes can accompany identity deployments. Pair this monitor with HSTS regression monitoring and CORS header checks when browser-based clients call identity endpoints directly.
Alert on meaningful differences
Generate a compact diff containing only safe metadata: changed field names, expected and observed hostnames, missing capabilities, status code, response time, and the check timestamp. Classify issuer, endpoint-host, and JWKS failures as critical. Treat newly added optional capabilities as informational. This makes alerts actionable without exposing tokens, cookies, or client secrets.
Use retries only for transient DNS or connection errors. Deterministic metadata mismatches should alert immediately. The guidance in cron job retry strategies helps separate temporary network failures from persistent configuration problems.
A practical rollout checklist
- Copy the exact discovery URL from a production client configuration.
- List the fields and capabilities that the application truly requires.
- Create one scheduled JSON validation check.
- Add a separate JWKS integrity check.
- Set strict timeouts and an approved redirect policy.
- Send sanitized field-level differences to the identity-owning team.
- Test the alert by changing a non-production baseline.
- Review the contract after planned provider or library upgrades.
Monitor without performing a login
Discovery and JWKS checks are public, read-only, and inexpensive. They should not create accounts, request tokens, or consume a user's authorization flow. A separate synthetic login can be useful for end-to-end coverage, but it requires stronger secret handling and cleanup. Begin with metadata monitoring because it catches a broad class of failures with little operational risk.
An OAuth discovery monitor turns identity configuration into an observable contract. By validating issuer consistency, endpoint safety, supported capabilities, signing keys, redirects, and latency on a schedule, teams can catch authentication regressions early while keeping the check simple and free of sensitive data.