From 571bd60d824741a25d8cfc288be55e373bef364a Mon Sep 17 00:00:00 2001
From: Joe Grandja <10884212+jgrandja@users.noreply.github.com>
Date: Tue, 4 Nov 2025 14:23:37 -0500
Subject: [PATCH] Document OAuth 2.0 Protected Resource Metadata support

Issue gh-17244
---
 docs/modules/ROOT/nav.adoc                    |  1 +
 .../protected-resource-metadata.adoc          | 28 +++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/servlet/oauth2/resource-server/protected-resource-metadata.adoc

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index ad2a966ffb..0d86d82e91 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -90,6 +90,7 @@
 **** xref:servlet/oauth2/resource-server/multitenancy.adoc[Multitenancy]
 **** xref:servlet/oauth2/resource-server/bearer-tokens.adoc[Bearer Tokens]
 **** xref:servlet/oauth2/resource-server/dpop-tokens.adoc[DPoP-bound Access Tokens]
+**** xref:servlet/oauth2/resource-server/protected-resource-metadata.adoc[Protected Resource Metadata]
 *** xref:servlet/oauth2/authorization-server/index.adoc[OAuth2 Authorization Server]
 **** xref:servlet/oauth2/authorization-server/getting-started.adoc[Getting Started]
 **** xref:servlet/oauth2/authorization-server/configuration-model.adoc[Configuration Model]
diff --git a/docs/modules/ROOT/pages/servlet/oauth2/resource-server/protected-resource-metadata.adoc b/docs/modules/ROOT/pages/servlet/oauth2/resource-server/protected-resource-metadata.adoc
new file mode 100644
index 0000000000..15d9803f53
--- /dev/null
+++ b/docs/modules/ROOT/pages/servlet/oauth2/resource-server/protected-resource-metadata.adoc
@@ -0,0 +1,28 @@
+[[oauth2resourceserver-protected-resource-metadata]]
+= OAuth 2.0 Protected Resource Metadata
+
+`OAuth2ResourceServerConfigurer.ProtectedResourceMetadataConfigurer` provides the ability to customize the https://www.rfc-editor.org/rfc/rfc9728.html#section-3[OAuth 2.0 Protected Resource Metadata endpoint].
+It defines an extension point that lets you customize the https://www.rfc-editor.org/rfc/rfc9728.html#section-3.2[OAuth 2.0 Protected Resource Metadata response].
+
+`OAuth2ResourceServerConfigurer.ProtectedResourceMetadataConfigurer` provides the following configuration option:
+
+[source,java]
+----
+@Bean
+public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+	http
+		.oauth2ResourceServer((resourceServer) ->
+			resourceServer
+				.protectedResourceMetadata(protectedResourceMetadata ->
+                    protectedResourceMetadata
+                        .protectedResourceMetadataCustomizer(protectedResourceMetadataCustomizer)   <1>
+				)
+		);
+
+	return http.build();
+}
+----
+<1> `protectedResourceMetadataCustomizer()`: The `Consumer` providing access to the `OAuth2ProtectedResourceMetadata.Builder` allowing the ability to customize the claims of the Resource Server's configuration.
+
+`OAuth2ResourceServerConfigurer.ProtectedResourceMetadataConfigurer` configures the `OAuth2ProtectedResourceMetadataFilter` and registers it with the Resource Server `SecurityFilterChain` `@Bean`.
+`OAuth2ProtectedResourceMetadataFilter` is the `Filter` that returns the https://www.rfc-editor.org/rfc/rfc9728.html#section-3.2[OAuth2ProtectedResourceMetadata response].