From 95b2cdf7f46e35e8eb17b0f04eda67f45924485f Mon Sep 17 00:00:00 2001
From: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
Date: Fri, 27 Mar 2026 11:41:12 -0600
Subject: [PATCH] Clarify JavaDoc

Removed note about DelegatingJwtGrantedAuthoritiesConverter from
ExpressionJwtGrantedAuthoritiesConverter and further explained in
DelegatingJwtGrantedAuthoritiesConverter where it comes in handy.

Issue gh-18300

Signed-off-by: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
---
 ...elegatingJwtGrantedAuthoritiesConverter.java | 17 +++++++++++++++++
 ...xpressionJwtGrantedAuthoritiesConverter.java |  3 ---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DelegatingJwtGrantedAuthoritiesConverter.java b/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DelegatingJwtGrantedAuthoritiesConverter.java
index 75cbaffa86..218a4a5169 100644
--- a/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DelegatingJwtGrantedAuthoritiesConverter.java
+++ b/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DelegatingJwtGrantedAuthoritiesConverter.java
@@ -30,6 +30,23 @@ import org.springframework.util.Assert;
  * A {@link Jwt} to {@link GrantedAuthority} {@link Converter} that is a composite of
  * converters.
  *
+ * <p>
+ * This is handy when needing to read authorities from multiple locations in a JWT; each
+ * underlying converter is called in series and the results are aggregated into a single
+ * collection of authorities.
+ *
+ * <p>
+ * For example, you might have a claim called "scope" and another called "roles". With
+ * {@link DelegatingJwtGrantedAuthoritiesConverter}, you can do:
+ *
+ * <code>
+ *   JwtGrantedAuthoritiesConverter scopes = new JwtGrantedAuthoritiesConverter();
+ *   JwtGrantedAuthoritiesConverter roles = new JwtGrantedAUthoritiesConverter();
+ *   roles.setAuthoritiesClaimName("roles");
+ *   roles.setAuthorityPrefix("ROLE_");
+ *   return new DelegatingJwtGrantedAuthoritiesConverter(scopes, roles);
+ * </code>
+ *
  * @author Laszlo Stahorszki
  * @author Josh Cummings
  * @since 5.5
diff --git a/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/ExpressionJwtGrantedAuthoritiesConverter.java b/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/ExpressionJwtGrantedAuthoritiesConverter.java
index 01576dbfc0..3120cd7fc7 100644
--- a/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/ExpressionJwtGrantedAuthoritiesConverter.java
+++ b/oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/ExpressionJwtGrantedAuthoritiesConverter.java
@@ -36,9 +36,6 @@ import org.springframework.util.Assert;
  * Uses an expression for extracting the token claim value to use for mapping
  * {@link GrantedAuthority authorities}.
  *
- * Note this can be used in combination with a
- * {@link DelegatingJwtGrantedAuthoritiesConverter}.
- *
  * @author Thomas Darimont
  * @since 6.4
  */