oauth-discovery 1.0.0

OAuth / OIDC Discovery Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: oauth-discovery
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site

Abstract

This check validates OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery metadata when a site exposes or claims OAuth/OIDC support. It probes the registered well-known discovery locations, validates the returned JSON against the relevant OAuth or OIDC profile, and performs lightweight endpoint checks for advertised authorization, token, and JWKS endpoints.

The check is claim-based. A generic login form, Google sign-in button, email/password flow, or dashboard-generated API key flow does not by itself make OAuth/OIDC discovery applicable.

Motivation

Agents and API clients should not scrape login pages or guess authorization endpoints. OAuth/OIDC discovery gives clients a standards-backed way to find issuers, authorization endpoints, token endpoints, supported response types, grant types, PKCE support, and signing keys.

This matters most when a site operates an authorization server, exposes delegated user access, supports third-party app connections, publishes MCP or API resources that require OAuth, or points clients to an OpenID Provider.

Normative Model

The check recognizes two registered well-known discovery surfaces:

• /.well-known/oauth-authorization-server, defined by RFC 8414.
• /.well-known/openid-configuration, defined by OpenID Connect Discovery 1.0.

For OAuth authorization-server metadata, the check validates the RFC 8414 shape. issuer and response_types_supported are required. authorization_endpoint and token_endpoint are required when the advertised or defaulted grants need them. grant_types_supported is optional and defaults to authorization_code and implicit when omitted. jwks_uri is optional for pure OAuth metadata.

For OIDC provider metadata, the check applies the stricter OIDC profile. OIDC metadata requires fields such as issuer, authorization_endpoint, jwks_uri, response_types_supported, subject_types_supported, and id_token_signing_alg_values_supported.

When a document mixes OAuth AS and OIDC metadata, the check treats it as a hybrid profile and applies the stronger relevant requirements.

Applicability

The check is applicable when at least one of these is true:

• A discovery document is found at /.well-known/openid-configuration.
• A discovery document is found at /.well-known/oauth-authorization-server.
• The homepage, headers, or linked metadata claim OAuth/OIDC support.
• The page references OAuth, OIDC, OpenID Connect, PKCE, authorization code, token endpoints, scopes, client IDs, client secrets, redirect URIs, or registered OAuth/OIDC discovery paths.
• HTTP headers point to OAuth/OIDC discovery or Bearer resource_metadata.

The check is not applicable when:

• no discovery document is found,
• no OAuth/OIDC claim is detected,
• and the only signals are generic authentication mechanisms such as login, Google sign-in, email/password, account pages, API keys, bearer API tokens, or dashboards.

API-key-only SaaS products should document API-key setup through auth documentation, OpenAPI security schemes, API catalog links, MCP metadata, or auth.md; they should not publish OAuth/OIDC discovery unless they operate a real OAuth/OIDC authorization server.

Pass Criteria

The check passes when:

• at least one appropriate discovery document is fetched with HTTP 2xx,
• the response is JSON or a +json media type,
• OIDC and hybrid discovery documents include Access-Control-Allow-Origin: * so browser-based clients and SPAs can read them,
• the document has the required fields for its detected profile,
• URL-valued fields are absolute HTTPS URLs,
• advertised authorization and token endpoints return protocol-shaped responses,
• unknown clients are not redirected to unregistered callback URLs,
• and jwks_uri returns usable JWKs with browser-readable CORS headers when OIDC or signed-token metadata requires it.

Warning Criteria

Warnings include:

• only generic human-login, account, dashboard, API-key, or bearer-token signals are present and no OAuth/OIDC discovery claim is found
• a valid discovery document is present but optional capabilities such as grant types, scopes, PKCE support, response modes, or revocation/introspection metadata are incomplete
• OIDC/hybrid metadata is valid but browser-readable CORS evidence is incomplete
• endpoint probes return protocol-shaped errors but weak content types or limited diagnostic detail
• JWKS is present but missing recommended key metadata such as kid, alg, or cache guidance

Failure Criteria

Failures include:

• the site claims OAuth/OIDC support but no authorization-server or OpenID discovery document is fetchable
• a discovery document is not JSON-compatible, not valid JSON, or has an invalid root shape
• required profile fields are missing
• URL-valued fields are not absolute HTTPS URLs
• issuer identity is malformed, such as a non-HTTPS issuer URL or an issuer URL with query or fragment
• authorization, token, JWKS, or other required endpoints are missing or malformed
• endpoint probes redirect unknown clients to unregistered callback URLs
• jwks_uri is required but missing, unreachable, invalid, or not browser-readable where OIDC clients need it
• public discovery metadata exposes secrets, tokens, cookies, private keys, or credential-bearing URLs

Evidence Model

The result emits:

• applicability signals and generic auth signals,
• discovery paths checked,
• selected metadata profile,
• fetch status and content type,
• missing fields, warnings, endpoint URL issues,
• normalized endpoint values,
• inferred default grant types,
• discovery and JWKS CORS evidence, including Access-Control-Allow-Origin,
• endpoint probe status, HTTP status, content type, and short excerpts,
• redirect-safety probe result,
• JWKS key count and sanitized key summaries containing only kid, kty, and alg.

Full tokens, credentials, cookies, authorization headers, and private key material must not appear in evidence.

Validation/Scoring Steps

• applicability (0.15): decide whether OAuth/OIDC is claimed or discovered.
• fetch (0.20): fetch registered well-known discovery candidates.
• validate (0.25): validate the metadata profile.
• discovery-cors (0.05): verify browser-based clients can read the discovery document.
• authorization-endpoint (0.15): send a syntactically shaped authorization-code probe.
• authorization-redirect-safety (0.10): verify an unknown client is not redirected to an untrusted callback URL.
• token-endpoint (0.05): send a harmless invalid-code token probe using an advertised or defaulted grant type.
• jwks (0.05): validate JWKS and browser fetchability when required by OIDC or signed-token metadata.

Standard Behavior

Missing metadata is not_applicable unless OAuth/OIDC is claimed. If OAuth/OIDC is claimed but no discovery document is found, the check fails. If a document is found, the check validates it even when the homepage does not visibly advertise auth.

For pure RFC 8414 OAuth metadata, omitted grant_types_supported is treated as the standards-defined default. Omitted jwks_uri is a warning rather than a failure unless OIDC or signed-token behavior requires keys.

For OIDC metadata, missing jwks_uri, subject_types_supported, or id_token_signing_alg_values_supported is a failure.

For OIDC and hybrid metadata, missing Access-Control-Allow-Origin: * on the discovery response or JWKS response is a failure because browser-based OAuth/OIDC clients and SPAs cannot reliably read those public metadata documents cross-origin. For pure OAuth authorization-server metadata, missing wildcard CORS is a warning unless other evidence indicates browser/agent UI access requires it.

Non-Standard And Real-World Behavior

Major providers commonly publish OIDC discovery metadata. Some providers use path-bearing issuer patterns for tenants or custom authorization servers. This version primarily checks the site-root well-known locations and homepage/header claims; future versions may expand candidate discovery through linked issuer URLs and protected-resource metadata.

This version does not fail solely because an issuer path differs from the well-known discovery path. Issuer-to-discovery-path consistency for tenant and custom authorization-server deployments needs a clearer product rule before it can be enforced deterministically.

Some authorization endpoints return provider-branded errors or HTML for unknown clients. The check accepts protocol-shaped OAuth errors and redirects as operational evidence, but fails clear 404, 405, 5xx, or unsupported advertised grants.

OpenID Connect Discovery recommends CORS support for JavaScript clients. In practice, public discovery and JWKS documents should be served with Access-Control-Allow-Origin: * because they contain public metadata and signing keys intended for broad client discovery.

Non-Goals And Limitations

• The check does not complete a real OAuth login or consent flow.
• The check does not register a real OAuth client.
• The check does not validate issued tokens.
• The check does not treat ordinary Google login, email/password login, or API-key generation as OAuth/OIDC authorization-server support.
• The check does not replace the separate OAuth Protected Resource metadata check.

References

• www.rfc-editor.org/rfc/rfc8414
• openid.net/specs/openid-connect-discovery-1_0.html
• www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
• www.rfc-editor.org/rfc/rfc9700
• www.rfc-editor.org/rfc/rfc9207
• www.rfc-editor.org/rfc/rfc7636
• modelcontextprotocol.io/specification/2025-11-25/basic/authorization

oauth-discovery v1.0.0 Changelog

• Changed applicability from generic auth/login signals to OAuth/OIDC claim or discovery evidence.
• Added profile-aware OAuth authorization-server, OIDC provider, and hybrid metadata validation.
• Treated RFC 8414 optional fields such as grant_types_supported and pure-OAuth jwks_uri according to their standards-defined behavior.
• Added explicit discovery and JWKS CORS validation for browser-based OAuth/OIDC clients and SPAs.
• Preserved endpoint probing, token endpoint probing, JWKS validation, and authorization redirect-safety checks.