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 — 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

Topic: openidConnectClient-1.0 feature page

Change 1 Add to the Examples list

Add the following entry to the existing list of examples near the top of the page:

Serve OAuth protected resource metadata (RFC 9728)

Change 2 - Add to the openidConnectClient element configuration reference

In the attribute/element table for openidConnectClient, add a new sub-element row:

Sub-element	Description
protectedResourceMetadata	Optional. Enables serving of an OAuth 2.0 Protected Resource Metadata document (RFC 9728) and adds the resource_metadata URI to WWW-Authenticate headers on 401 responses. See Serve OAuth protected resource metadata (RFC 9728).

Change 3 - Add a note to the 401 / WWW-Authenticate section

Add the following note wherever the existing page discusses 401 responses or WWW-Authenticate header handling:

Note: When <protectedResourceMetadata> is configured, Liberty automatically appends the resource_metadata URI to the WWW-Authenticate response header on 401 rejections.

Change 4 - Add a new section at the end of the Examples

Add the following new section after the existing "Check the access token for user and group information" example:

---

Serve 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.

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.

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.

Related information

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

[Azquelt]

Rather than creating a new topic page, I think it would make sense to add the information to the OpenID Connect Client feature reference page as that's where we seem to document the functionality of this feature.

@IssacAX123 wdyt?

[ramkumar-k-9286]

@Azquelt @IssacAX123

Please let me know how you want to proceed.

Regards,
Ramkumar

[Azquelt]

@ramkumar-k-9286 We think the info that was to go on a new page should instead go in the OpenID Connect Client feature reference page.

We'll get the issue updated later today.

[IssacAX123]

@ramkumar-k-9286 I have updated the issue to integrate with OpenID Connect Client feature reference page.