Documentation, Support for OAuth protected resource metadata

[IssacAX123]

Documentation, Support for OAuth protected resource metadata

Feature epic details

• Documentation, Support for OAuth protected resource metadata
• Link to development epic: Support for OAuth protected resource metadata open-liberty#33381
• Target GA release: 26.0.0.9

Operating systems

Does the documentation apply to all operating systems?

• Yes

Summary

OAuth 2.0 Protected Resource Metadata (RFC 9728) defines a standard JSON document that a resource server publishes at /.well-known/oauth-protected-resource to advertise which authorization server clients should use to obtain access tokens, what scopes are available, and how tokens are signed or encrypted.

Liberty now supports serving this metadata document when configured as an OAuth/OIDC resource server using openidConnectClient. This matters most for MCP servers (mcp-1.0), where the MCP specification requires protected resource metadata so that MCP clients can automatically discover the authorization flow without any pre-configuration.

Two related behaviours are introduced:

1. Augment 401 WWW-Authenticate responses with the resource_metadata URL pointing to that document (#34722)
2. Serve the metadata document at /.well-known/oauth-protected-resource (#34721)

Opt-in is required meaning existing openidConnectClient configurations are unaffected unless the new <protectedResourceMetadata> sub-element is added (#35129).

Configuration

A new optional sub-element <protectedResourceMetadata> is added inside <openidConnectClient>. Its presence enables protected resource metadata serving.

Attributes:

Attribute	Type	Required	Default	Description
advertisedScopes	String (comma-separated)	No	-	Scopes to publish in the metadata document (e.g. toys_browse, cart_read)
jwtBuilderRef	String	No	-	Reference to a <jwtBuilder> element used to sign the metadata JWT.

Example basic configuration:

<openidConnectClient id="protected-resource-demo"
    clientId="protected-resource"
    clientSecret="..."
    jwkEndpointUrl="https://auth.example.com/oidc/endpoint/SampleProvider/jwk"
    tokenEndpointAuthMethod="basic"
    issuerIdentifier="https://auth.example.com/oidc/endpoint/SampleProvider"
    authFilterRef="mcpAuthFilter"
    inboundPropagation="required">

    <protectedResourceMetadata
        advertisedScopes="toys_browse, toys_search, cart_read, cart_write"/>

</openidConnectClient>

Behaviour when enabled:

• The metadata document is served at /.well-known/oauth-protected-resource/<path> for each path covered by the configured authFilter.
• Requests for paths not protected by any openidConnectClient return 404.
• 401 responses for protected resources include the resource_metadata parameter in the WWW-Authenticate header, pointing to the metadata URL.

Updates to existing topics

1. openidConnectClient configuration reference

Add a new sub-element entry for <protectedResourceMetadata> in the attribute/element table, documenting the advertisedScopes and jwtBuilderRef attributes as described in the Configuration section above. Also add a cross-reference link to the new topic "Serving OAuth protected resource metadata (RFC 9728)".

Example: 401 response with resource_metadata

When a request to a protected resource is rejected because no valid token is present, Liberty returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="oauth", resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource/myApp/protected"

The resource_metadata URL points to the metadata document for the specific protected path. A client can follow this URL to discover the authorization server automatically.

2. 401 responses / WWW-Authenticate header handling

Add a note that when <protectedResourceMetadata> is configured, Liberty automatically appends the resource_metadata URI to the WWW-Authenticate response header on 401 rejections, per RFC 9728 §5.

Create a new topic

Topic title: Serving OAuth protected resource metadata (RFC 9728)

OAuth 2.0 Protected Resource Metadata (RFC 9728) allows a resource server to publish a well-known JSON document describing how clients can obtain access tokens. This enables MCP clients and other OAuth clients to automatically discover the authorization server without any prior configuration.

Enabling protected resource metadata

Add a <protectedResourceMetadata> sub-element to your <openidConnectClient> configuration. When present, Liberty:

• Serves the metadata document at /.well-known/oauth-protected-resource/<protected-path> for every path matched by the configured authFilter.
• Includes the resource_metadata URI in the WWW-Authenticate response header whenever a request to a protected resource is rejected with a 401 status code.

<openidConnectClient id="protected-resource-demo"
    clientId="protected-resource"
    clientSecret="..."
    jwkEndpointUrl="https://auth.example.com/oidc/endpoint/SampleProvider/jwk"
    tokenEndpointAuthMethod="basic"
    issuerIdentifier="https://auth.example.com/oidc/endpoint/SampleProvider"
    authFilterRef="mcpAuthFilter"
    inboundPropagation="required">

    <protectedResourceMetadata
        advertisedScopes="toys_browse, toys_search, cart_read, cart_write"/>

</openidConnectClient>

Example: metadata document

When a client sends a GET request to /.well-known/oauth-protected-resource/myApp/protected, Liberty responds with:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resource": "https://resource.example.com/myApp/protected",
  "authorization_servers": ["https://auth.example.com/oidc/endpoint/SampleProvider"],
  "scopes_supported": ["toys_browse", "toys_search", "cart_read", "cart_write"]
}

• resource — the absolute URL of the protected resource
• authorization_servers — populated from the issuerIdentifier attribute of the matching <openidConnectClient>. If issuerIdentifier is not set, Liberty falls back to deriving the authorization server from validationEndpointUrl by stripping its last path segment (e.g. https://as.example.com/introspect → https://as.example.com). If neither is configured, the field is omitted.
• scopes_supported — present only when advertisedScopes is configured on <protectedResourceMetadata>; omitted otherwise.

Related information

• RFC 9728: OAuth 2.0 Protected Resource Metadata
• MCP Authorization specification