9.2.1

RESTHeart 9.2.1 Release Notes

What's New

OAuth 2.1 Authorization Code + PKCE Flow

RESTHeart 9.2.1 completes the OAuth 2.1 Authorization Code flow with PKCE support (RFC 7636), the recommended approach for authenticating users via a frontend login UI — including MCP clients such as Claude Desktop via mcp-remote.

Two new endpoints are introduced:

• GET /authorize — starts the OAuth 2.1 flow, redirecting the user to the configured login page.
• POST /authorize — completes the Authorization Code flow by receiving credentials from the login page and issuing the authorization code.

Both endpoints are disabled by default and must be explicitly enabled in the configuration.

Form-Based Credentials on POST /authorize

POST /authorize now accepts user credentials either as HTTP Basic Auth (header Authorization: Basic ...) or as form body (application/x-www-form-urlencoded with username and password fields). This makes the endpoint compatible with standard HTML browser forms without additional JavaScript. When both methods are present, the Basic Auth header takes precedence.

On invalid credentials, RESTHeart redirects to login-url?error=invalid_credentials&<original_query_params>, allowing the login page to display the error while preserving the OAuth context.

Account Properties Propagated to Authorization Code JWT

Account properties are now included in the authorization code JWT issued by POST /authorize. This ensures that user information (roles, custom attributes, etc.) is available in the intermediate token, consistent with the final access token behaviour.

OAuth Protected Resource Metadata — RFC 9728

New endpoint GET /.well-known/oauth-protected-resource (RFC 9728), implemented by oauthProtectedResourceMetadataService. MCP clients and other OAuth consumers can query it to automatically discover the authorization server before starting the OAuth flow. Supports path-specific metadata (e.g. /.well-known/oauth-protected-resource/mcp/ade).

Disabled by default from version 9.2.1.

Configuration Changes: server-url → base-url and enabled Flag

In OAuth metadata services (oauthAuthorizationServerMetadataService and oauthProtectedResourceMetadataService):

• The server-url option has been renamed to base-url.
• A new enabled flag has been added to explicitly control service activation.

Update your configuration accordingly:

oauthAuthorizationServerMetadataService:
  enabled: true          # new
  base-url: null         # was server-url
  authorize-endpoint-uri: /authorize
 
oauthProtectedResourceMetadataService:
  enabled: true          # new
  base-url: null         # was server-url

OAuth Services Disabled by Default

Starting from 9.2.1, all three optional OAuth services (oauthAuthorizationService, oauthAuthorizationServerMetadataService, oauthProtectedResourceMetadataService) are disabled by default. In 9.2.0 the metadata services were automatically enabled. This change prevents accidental exposure of unconfigured endpoints.

CORS Preflight Exemption for GetRoleService

The GetRoleService veto rule now correctly exempts CORS preflight requests (OPTIONS), preventing spurious authentication errors on browser preflight requests.

---

Migration Guide from 9.2.0

Action required	Detail
Update OAuth metadata configuration	Rename server-url → base-url; add enabled: true if the services were active
Check metadata services activation	Now disabled by default — enable them explicitly if needed

---

Full Changelog

Commit	Description
1cfe20d	Propagate account properties to OAuth auth-code JWT
bf48411	Add OAuth form-based credentials support for POST /authorize
c034a59	Enable OAuth metadata services in test config
2f10ef7	Add enabled flag and rename server-url to base-url in OAuth metadata services
ddd25a8	Disable OAuth authorization service by default and add PKCE tests
1a38ce3	Add OAuth 2.1 authorization endpoint (GET/POST /authorize)
419db21	Add OAuth 2.0 Protected Resource Metadata endpoint (RFC 9728)
689bec4	Add CORS preflight exemption to GetRoleService veto rule