Update javadoc

Signed-off-by: Tran Ngoc Nhan <ngocnhan.tran1996@gmail.com>

Author: ngocnhan-tran1996

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/introspection/SpringOpaqueTokenIntrospector.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,6 +20,7 @@
 import java.net.URI;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -79,8 +80,8 @@ public class SpringOpaqueTokenIntrospector implements OpaqueTokenIntrospector {
 	/**
 	 * Creates a {@code OpaqueTokenAuthenticationProvider} with the provided parameters
 	 * @param introspectionUri The introspection endpoint uri
-	 * @param clientId The client id authorized to introspect
-	 * @param clientSecret The client's secret
+	 * @param clientId The URL-encoded client id authorized to introspect
+	 * @param clientSecret The URL-encoded client secret authorized to introspect
 	 * @deprecated Please use {@link SpringOpaqueTokenIntrospector.Builder}
 	 */
 	@Deprecated(since = "6.5", forRemoval = true)
@@ -330,54 +331,28 @@ private Builder(String introspectionUri) {
 		}
 
 		/**
-		 * Uses the given parameters to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientId The client id authorized that should be encoded
-		 * @param charset The charset to use
-		 * @return the {@link SpringOpaqueTokenIntrospector.Builder}
-		 * @since 6.5
-		 */
-		public Builder clientId(String clientId, Charset charset) {
-			Assert.notNull(clientId, "clientId cannot be null");
-			Assert.notNull(charset, "charset cannot be null");
-			this.clientId = URLEncoder.encode(clientId, charset);
-			return this;
-		}
-
-		/**
-		 * Uses the given parameter to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientId The client id authorized
+		 * The builder will {@link URLEncoder encode} the client id that you provide, so
+		 * please give the unencoded value.
+		 * @param clientId The unencoded client id
 		 * @return the {@link SpringOpaqueTokenIntrospector.Builder}
 		 * @since 6.5
 		 */
 		public Builder clientId(String clientId) {
 			Assert.notNull(clientId, "clientId cannot be null");
-			this.clientId = clientId;
-			return this;
-		}
-
-		/**
-		 * Uses the given parameters to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientSecret The client's secret that should be encoded
-		 * @param charset The charset to use
-		 * @return the {@link SpringOpaqueTokenIntrospector.Builder}
-		 * @since 6.5
-		 */
-		public Builder clientSecret(String clientSecret, Charset charset) {
-			Assert.notNull(clientSecret, "clientSecret cannot be null");
-			Assert.notNull(charset, "charset cannot be null");
-			this.clientSecret = URLEncoder.encode(clientSecret, charset);
+			this.clientId = URLEncoder.encode(clientId, StandardCharsets.UTF_8);
 			return this;
 		}
 
 		/**
-		 * Uses the given parameter to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientSecret The client's secret
+		 * The builder will {@link URLEncoder encode} the client secret that you provide,
+		 * so please give the unencoded value.
+		 * @param clientSecret The unencoded client secret
 		 * @return the {@link SpringOpaqueTokenIntrospector.Builder}
 		 * @since 6.5
 		 */
 		public Builder clientSecret(String clientSecret) {
 			Assert.notNull(clientSecret, "clientSecret cannot be null");
-			this.clientSecret = clientSecret;
+			this.clientSecret = URLEncoder.encode(clientSecret, StandardCharsets.UTF_8);
 			return this;
 		}
 

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/introspection/SpringReactiveOpaqueTokenIntrospector.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,7 +19,7 @@
 import java.io.Serial;
 import java.net.URI;
 import java.net.URLEncoder;
-import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -74,8 +74,8 @@ public class SpringReactiveOpaqueTokenIntrospector implements ReactiveOpaqueToke
 	 * Creates a {@code OpaqueTokenReactiveAuthenticationManager} with the provided
 	 * parameters
 	 * @param introspectionUri The introspection endpoint uri
-	 * @param clientId The client id authorized to introspect
-	 * @param clientSecret The client secret for the authorized client
+	 * @param clientId The URL-encoded client id authorized to introspect
+	 * @param clientSecret The URL-encoded client secret authorized to introspect
 	 * @deprecated Please use {@link SpringReactiveOpaqueTokenIntrospector.Builder}
 	 */
 	@Deprecated(since = "6.5", forRemoval = true)
@@ -284,54 +284,28 @@ private Builder(String introspectionUri) {
 		}
 
 		/**
-		 * Uses the given parameters to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientId The client id authorized that should be encoded
-		 * @param charset The charset to use
-		 * @return the {@link SpringReactiveOpaqueTokenIntrospector.Builder}
-		 * @since 6.5
-		 */
-		public Builder clientId(String clientId, Charset charset) {
-			Assert.notNull(clientId, "clientId cannot be null");
-			Assert.notNull(charset, "charset cannot be null");
-			this.clientId = URLEncoder.encode(clientId, charset);
-			return this;
-		}
-
-		/**
-		 * Uses the given parameter to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientId The client id authorized
+		 * The builder will {@link URLEncoder encode} the client id that you provide, so
+		 * please give the unencoded value.
+		 * @param clientId The unencoded client id
 		 * @return the {@link SpringReactiveOpaqueTokenIntrospector.Builder}
 		 * @since 6.5
 		 */
 		public Builder clientId(String clientId) {
 			Assert.notNull(clientId, "clientId cannot be null");
-			this.clientId = clientId;
-			return this;
-		}
-
-		/**
-		 * Uses the given parameters to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientSecret The client's secret that should be encoded
-		 * @param charset The charset to use
-		 * @return the {@link SpringReactiveOpaqueTokenIntrospector.Builder}
-		 * @since 6.5
-		 */
-		public Builder clientSecret(String clientSecret, Charset charset) {
-			Assert.notNull(clientSecret, "clientSecret cannot be null");
-			Assert.notNull(charset, "charset cannot be null");
-			this.clientSecret = URLEncoder.encode(clientSecret, charset);
+			this.clientId = URLEncoder.encode(clientId, StandardCharsets.UTF_8);
 			return this;
 		}
 
 		/**
-		 * Uses the given parameter to build {@code SpringOpaqueTokenIntrospector}
-		 * @param clientSecret The client's secret
+		 * The builder will {@link URLEncoder encode} the client secret that you provide,
+		 * so please give the unencoded value.
+		 * @param clientSecret The unencoded client secret
 		 * @return the {@link SpringReactiveOpaqueTokenIntrospector.Builder}
 		 * @since 6.5
 		 */
 		public Builder clientSecret(String clientSecret) {
 			Assert.notNull(clientSecret, "clientSecret cannot be null");
-			this.clientSecret = clientSecret;
+			this.clientSecret = URLEncoder.encode(clientSecret, StandardCharsets.UTF_8);
 			return this;
 		}
 

oauth2/oauth2-resource-server/src/test/java/org/springframework/security/oauth2/server/resource/introspection/SpringOpaqueTokenIntrospectorTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -364,22 +364,22 @@ public void introspectWithEncodeClientCredentialsThenOk() throws Exception {
 			String response = """
 					{
 						"active": true,
-						"username": "client%&1"
+						"username": "client&1"
 					}
 					""";
-			server.setDispatcher(requiresAuth("client%25%261", "secret%40%242", response));
+			server.setDispatcher(requiresAuth("client%261", "secret%40%242", response));
 			String introspectUri = server.url("/introspect").toString();
 			OpaqueTokenIntrospector introspectionClient = SpringOpaqueTokenIntrospector
 				.withIntrospectionUri(introspectUri)
-				.clientId("client%&1", StandardCharsets.UTF_8)
-				.clientSecret("secret@$2", StandardCharsets.UTF_8)
+				.clientId("client&1")
+				.clientSecret("secret@$2")
 				.build();
 			OAuth2AuthenticatedPrincipal authority = introspectionClient.introspect("token");
 			// @formatter:off
 			assertThat(authority.getAttributes())
 					.isNotNull()
 					.containsEntry(OAuth2TokenIntrospectionClaimNames.ACTIVE, true)
-					.containsEntry(OAuth2TokenIntrospectionClaimNames.USERNAME, "client%&1");
+					.containsEntry(OAuth2TokenIntrospectionClaimNames.USERNAME, "client&1");
 			// @formatter:on
 		}
 	}

oauth2/oauth2-resource-server/src/test/java/org/springframework/security/oauth2/server/resource/introspection/SpringReactiveOpaqueTokenIntrospectorTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -288,22 +288,22 @@ public void introspectWithEncodeClientCredentialsThenOk() throws Exception {
 			String response = """
 					{
 						"active": true,
-						"username": "client%&1"
+						"username": "client&1"
 					}
 					""";
-			server.setDispatcher(requiresAuth("client%25%261", "secret%40%242", response));
+			server.setDispatcher(requiresAuth("client%261", "secret%40%242", response));
 			String introspectUri = server.url("/introspect").toString();
 			ReactiveOpaqueTokenIntrospector introspectionClient = SpringReactiveOpaqueTokenIntrospector
 				.withIntrospectionUri(introspectUri)
-				.clientId("client%&1", StandardCharsets.UTF_8)
-				.clientSecret("secret@$2", StandardCharsets.UTF_8)
+				.clientId("client&1")
+				.clientSecret("secret@$2")
 				.build();
 			OAuth2AuthenticatedPrincipal authority = introspectionClient.introspect("token").block();
 			// @formatter:off
 			assertThat(authority.getAttributes())
 					.isNotNull()
 					.containsEntry(OAuth2TokenIntrospectionClaimNames.ACTIVE, true)
-					.containsEntry(OAuth2TokenIntrospectionClaimNames.USERNAME, "client%&1");
+					.containsEntry(OAuth2TokenIntrospectionClaimNames.USERNAME, "client&1");
 			// @formatter:on
 		}
 	}