OAuth Authorization Server Auditor

Audit a public OAuth 2.0 authorization server's /.well-known/oauth-authorization-server discovery metadata in one API call. Validates the document against RFC 8414 (OAuth 2.0 Authorization Server Metadata): well-known URI construction, required metadata keys (conditional on supported grant types), issuer match against the fetched URL, https endpoint URLs, and PKCE support. Returns a readiness score, letter grade, per-check analysis, and recommendations. Built for API platform teams, OAuth/SSO infrastructure engineers, security auditors, and CI/CD pipelines.

This actor targets plain OAuth 2.0 authorization servers defined by RFC 8414 — API platforms, developer-tool OAuth providers, and authorization servers that are not full OpenID Connect identity providers. It does not audit OpenID Connect Discovery documents (/.well-known/openid-configuration); use a dedicated OIDC discovery auditor for that.

Use cases

• API platform teams - verify RFC 8414 metadata before publishing a new or upgraded OAuth 2.0 authorization server
• OAuth/SSO infrastructure engineers - confirm endpoint URLs, issuer value, and grant-type-conditional required fields are published correctly
• Security auditors - check for issuer mismatch (clients MUST reject mismatched metadata), missing https endpoints, and weak PKCE (plain)
• Devtool integrators - validate a third-party OAuth authorization server's metadata before wiring client libraries against it
• CI/CD pipelines - run automated conformance checks after OAuth authorization server configuration changes and alert on score drops

What it checks

• Discovery document - served at /.well-known/oauth-authorization-server with HTTP 200 and application/json Content-Type
• JSON validity - the document body parses as a JSON object
• Well-known URI construction (RFC 8414 section 3.1) - correctly inserts the well-known path segment BEFORE any issuer path component (https://example.com/.well-known/oauth-authorization-server/issuer1), unlike OIDC Discovery which appends after the path
• Required metadata keys - issuer is always required; authorization_endpoint and token_endpoint are required unless grant_types_supported indicates the server does not need them (e.g. a client_credentials-only server does not need authorization_endpoint); response_types_supported is required when authorization_endpoint is present
• Issuer match - the declared issuer value matches the URL used to construct the discovery document request (RFC 8414 section 3.3); issuer must not contain query or fragment components and must be https
• Endpoint URLs - every documented endpoint (authorization_endpoint, token_endpoint, jwks_uri, registration_endpoint, revocation_endpoint, introspection_endpoint) is a parseable https URL; off-issuer-origin endpoints are flagged as a warning (common on shared platforms)
• PKCE support - code_challenge_methods_supported advertises S256; plain alone is flagged per RFC 7636
• Recommended keys - jwks_uri, grant_types_supported, token_endpoint_auth_methods_supported, token_endpoint_auth_signing_alg_values_supported, revocation_endpoint (+ auth methods), introspection_endpoint (+ auth methods), code_challenge_methods_supported, service_documentation, ui_locales_supported, op_policy_uri, op_tos_uri, scopes_supported

Endpoint URLs found inside the metadata are never fetched - only the single discovery document on the provided issuer host is read.

Input

Field	Type	Required	Default	Description
startUrl	string	yes	-	Issuer URL of the OAuth 2.0 authorization server (domain, optionally with a path for multi-tenant issuers)
timeoutSeconds	integer	no	10	Per-request timeout (3-30 seconds)

Example input

{
  "startUrl": "github.com",
  "timeoutSeconds": 10
}

Output

A single dataset item with the full audit:

Field	Type	Description
inputIssuer	string	The issuer URL provided as input
discoveryUrl	string	The RFC 8414 /.well-known/oauth-authorization-server URL that was fetched
finalUrl	string	Final URL after redirects
https	boolean	Whether the discovery document was served over HTTPS
status	integer	Final HTTP status code
documentFound	boolean	Whether a 200 discovery document was served
jsonValid	boolean	Whether the document body is valid JSON
parseError	string | null	JSON parse error message, or null
issuer	string | null	Declared issuer value in the metadata
issuerMatchesFinalUrl	boolean	Whether the declared issuer matches the fetched URL
requiredKeys	array	Required metadata keys present for this document (conditional on grant types)
missingRequiredKeys	array	Required metadata keys missing
missingRecommendedKeys	array	Recommended metadata keys missing
metadataKeyCount	integer	Total metadata keys in the document
endpoints	array	Per-endpoint analysis (key, url, https, parseable, issuerHost, issues)
responseTypes	array | null	response_types_supported values
grantTypes	array | null	grant_types_supported values
scopes	array | null	scopes_supported values
codeChallengeMethods	array | null	code_challenge_methods_supported values (PKCE)
tokenAuthMethods	array | null	token_endpoint_auth_methods_supported values
tokenAuthSigningAlgs	array | null	token_endpoint_auth_signing_alg_values_supported values
revocationAuthMethods	array | null	revocation_endpoint_auth_methods_supported values
introspectionAuthMethods	array | null	introspection_endpoint_auth_methods_supported values
uiLocales	array | null	ui_locales_supported values
serviceDocumentation	string | null	service_documentation URL
opPolicyUri	string | null	op_policy_uri URL
opTosUri	string | null	op_tos_uri URL
pkceSupported	boolean	Whether PKCE code challenge methods are advertised
checks	array	Per-check analysis (name, status, note, weight, recommendation)
issues	array	Aggregated issue descriptions
score	integer	OAuth authorization server metadata readiness score (0-100)
grade	string	Letter grade (A+, A, B, C, D, E, F)
checkedAt	string	ISO 8601 timestamp
recommendations	array	Actionable recommendations

Example output (abridged)

{
  "inputIssuer": "github.com",
  "discoveryUrl": "https://github.com/.well-known/oauth-authorization-server",
  "documentFound": true,
  "jsonValid": true,
  "issuer": "https://github.com",
  "issuerMatchesFinalUrl": true,
  "missingRequiredKeys": [],
  "grantTypes": ["authorization_code"],
  "codeChallengeMethods": ["S256"],
  "pkceSupported": true,
  "score": 90,
  "grade": "A",
  "checks": [
    {
      "name": "Issuer match",
      "check": "issuer",
      "status": "good",
      "note": "issuer 'https://github.com' matches the discovery document URL.",
      "weight": 20,
      "recommendation": null
    }
  ],
  "recommendations": []
}

Security

• Public HTTP/HTTPS only; rejects URL credentials, localhost and private/link-local IPv4 and IPv6 literal ranges (RFC 1918, RFC 3927, and IPv6 unique-local/link-local equivalents, including bracketed IPv6 literals), and DNS resolutions to private IP ranges.
• Redirects are followed manually (up to 3 hops) and each hop is revalidated against the same SSRF checks before following.
• Fetches only the single /.well-known/oauth-authorization-server discovery document on the provided issuer host; endpoint URLs found inside the metadata are never fetched.
• Bounded body read (2 MB cap); no login, no JavaScript execution, no cookies, no stored page content.

Pricing

Pay-per-event: one scored audit per run (~$0.015/run).

Event	Price
Actor start	$0.005
Per domain audited	$0.01

FAQ

Does this fetch the JWKS or probe any OAuth endpoint? No. Only the discovery document is fetched. Endpoint URLs (authorization_endpoint, token_endpoint, jwks_uri, etc.) are validated as metadata strings so the actor cannot be used to probe arbitrary URLs.

Why does the well-known URL differ from OIDC Discovery? RFC 8414 section 3.1 inserts the /.well-known/oauth-authorization-server path segment before any issuer path component (https://example.com/.well-known/oauth-authorization-server/issuer1). OpenID Connect Discovery instead appends the well-known segment after the issuer path. This actor implements the RFC 8414 construction rule; it is not interchangeable with an OIDC discovery auditor.

Why does issuer mismatch matter? RFC 8414 section 3.3 requires the issuer value returned in the metadata to be identical to the issuer identifier used to construct the discovery document request URL. Conformant clients MUST reject metadata where they differ - a mismatch silently breaks client discovery and can be a sign of misconfiguration or a man-in-the-middle condition.

Does this work for authorization servers that only support client_credentials? Yes. authorization_endpoint is only treated as required when grant_types_supported indicates a grant type that uses it (authorization_code or implicit), or when grant_types_supported is absent (RFC 8414 defaults to authorization_code support). A client_credentials-only server correctly scores without authorization_endpoint.

Can I use this to audit a full OpenID Connect provider? This actor audits plain OAuth 2.0 authorization server metadata per RFC 8414. OpenID Connect providers publish a related but distinct discovery document (/.well-known/openid-configuration) with its own well-known URI construction rule; use a dedicated OIDC discovery auditor for those.

Local development

npm install
npm test        # node --test suite (parsers, SSRF, well-known URI construction, scoring, live smoke)
npm run lint    # node --check
python3 ../../scripts/audit_actor.py .   # portfolio security audit (run from actors/ dir)