Module: StandardId::Oauth::DiscoveryDocument

Defined in:
lib/standard_id/oauth/discovery_document.rb

Overview

Shared builder for the OIDC / OAuth 2.0 metadata documents served at:

* /.well-known/openid-configuration   (OpenID Connect Discovery)
* /.well-known/oauth-authorization-server (RFC 8414)

Both well-known controllers render this single builder so the two documents cannot drift. Endpoint URLs are derived from the configured issuer.

NOTE on mounting (RFC 8414 caveat): the ApiEngine is consumer-mounted at a sub-path (e.g. ‘/auth/api`), so the gem can only serve `/auth/api/.well-known/oauth-authorization-server`. A strict RFC 8414 client that derives a root-anchored metadata URL from a path-carrying issuer would probe `<host>/.well-known/oauth-authorization-server/auth/api`, which falls outside any engine mount. Hosts that need the root-anchored form must add their own root route — the gem cannot.

Class Method Summary collapse

Class Method Details

.build(issuer, registration_enabled: false) ⇒ Hash

Parameters:

  • issuer (String) —

    the configured issuer (e.g. “auth.example.com”)

  • registration_enabled (Boolean) (defaults to: false) —

    when true, advertises the RFC 7591 dynamic client registration endpoint. The well-known controllers pass ‘StandardId.config.oauth.dynamic_registration_enabled` here, so the `registration_endpoint` is emitted only when DCR is turned on. Defaults to false so callers (and tests) that omit it get no registration_endpoint.

Returns:

  • (Hash) 


28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/standard_id/oauth/discovery_document.rb', line 28

def build(issuer, registration_enabled: false)
  base = issuer.to_s.chomp("/")

  doc = {
    issuer: issuer,
    authorization_endpoint: "#{base}/authorize",
    token_endpoint: "#{base}/oauth/token",
    revocation_endpoint: "#{base}/oauth/revoke",
    userinfo_endpoint: "#{base}/userinfo",
    response_types_supported: %w[code],
    grant_types_supported: %w[authorization_code refresh_token client_credentials],
    subject_types_supported: %w[public],
    id_token_signing_alg_values_supported: [StandardId.config.oauth.signing_algorithm.to_s.upcase],
    # "none" advertises public-client support (PKCE-only token exchange,
    # no client_secret) per RFC 8414 — required by native/SPA/MCP clients.
    token_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post none],
    # PKCE is always enforced (require_pkce defaults true and cannot be
    # disabled for public clients), so advertise the supported method.
    code_challenge_methods_supported: %w[S256]
  }

  # Only advertise jwks_uri when signing is asymmetric. With symmetric
  # (HS256/384/512) signing there are no public keys to publish, so the
  # jwks endpoint deliberately returns 404 — advertising it would point
  # clients at a dead URL. HS-signed tokens are verified with the shared
  # secret, not JWKS. (RFC 8414 makes jwks_uri optional; an OIDC client
  # using HS256 id_tokens verifies them with the client_secret.)
  doc[:jwks_uri] = "#{base}/.well-known/jwks.json" if StandardId::JwtService.asymmetric?

  doc[:registration_endpoint] = "#{base}/oauth/register" if registration_enabled

  doc
end