Add documentation for DPoP support

Closes gh-17072

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DPoPAuthenticationProvider.java

@@ -50,10 +50,15 @@ import org.springframework.util.CollectionUtils;
 import org.springframework.util.StringUtils;
 
 /**
+ * An {@link AuthenticationProvider} implementation that is responsible for authenticating
+ * a DPoP-bound access token for a protected resource request.
+ *
  * @author Joe Grandja
  * @since 6.5
  * @see DPoPAuthenticationToken
  * @see DPoPProofJwtDecoderFactory
+ * @see <a target="_blank" href="https://datatracker.ietf.org/doc/html/rfc9449">RFC 9449
+ * OAuth 2.0 Demonstrating Proof of Possession (DPoP)</a>
  */
 public final class DPoPAuthenticationProvider implements AuthenticationProvider {
 
@@ -61,6 +66,11 @@ public final class DPoPAuthenticationProvider implements AuthenticationProvider
 
 	private JwtDecoderFactory<DPoPProofContext> dPoPProofVerifierFactory;
 
+	/**
+	 * Constructs a {@code DPoPAuthenticationProvider} using the provided parameters.
+	 * @param tokenAuthenticationManager the {@link AuthenticationManager} used to
+	 * authenticate the DPoP-bound access token
+	 */
 	public DPoPAuthenticationProvider(AuthenticationManager tokenAuthenticationManager) {
 		Assert.notNull(tokenAuthenticationManager, "tokenAuthenticationManager cannot be null");
 		this.tokenAuthenticationManager = tokenAuthenticationManager;
@@ -121,6 +131,13 @@ public final class DPoPAuthenticationProvider implements AuthenticationProvider
 		return DPoPAuthenticationToken.class.isAssignableFrom(authentication);
 	}
 
+	/**
+	 * Sets the {@link JwtDecoderFactory} that provides a {@link JwtDecoder} for the
+	 * specified {@link DPoPProofContext} and is used for authenticating a DPoP Proof
+	 * {@link Jwt}. The default factory is {@link DPoPProofJwtDecoderFactory}.
+	 * @param dPoPProofVerifierFactory the {@link JwtDecoderFactory} that provides a
+	 * {@link JwtDecoder} for the specified {@link DPoPProofContext}
+	 */
 	public void setDPoPProofVerifierFactory(JwtDecoderFactory<DPoPProofContext> dPoPProofVerifierFactory) {
 		Assert.notNull(dPoPProofVerifierFactory, "dPoPProofVerifierFactory cannot be null");
 		this.dPoPProofVerifierFactory = dPoPProofVerifierFactory;

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/DPoPAuthenticationToken.java

@@ -20,9 +20,14 @@ import java.io.Serial;
 import java.util.Collections;
 
 import org.springframework.security.authentication.AbstractAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.oauth2.jwt.Jwt;
 import org.springframework.util.Assert;
 
 /**
+ * An {@link Authentication} representing a protected resource request with a DPoP-bound
+ * access token.
+ *
  * @author Joe Grandja
  * @since 6.5
  * @see DPoPAuthenticationProvider
@@ -40,6 +45,14 @@ public class DPoPAuthenticationToken extends AbstractAuthenticationToken {
 
 	private final String resourceUri;
 
+	/**
+	 * Constructs a {@code DPoPAuthenticationToken} using the provided parameters.
+	 * @param accessToken the DPoP-bound access token
+	 * @param dPoPProof the DPoP Proof {@link Jwt}
+	 * @param method the value of the HTTP method of the request
+	 * @param resourceUri the value of the HTTP resource URI of the request, without query
+	 * and fragment parts
+	 */
 	public DPoPAuthenticationToken(String accessToken, String dPoPProof, String method, String resourceUri) {
 		super(Collections.emptyList());
 		Assert.hasText(accessToken, "accessToken cannot be empty");
@@ -62,18 +75,35 @@ public class DPoPAuthenticationToken extends AbstractAuthenticationToken {
 		return getAccessToken();
 	}
 
+	/**
+	 * Returns the DPoP-bound access token.
+	 * @return the DPoP-bound access token
+	 */
 	public String getAccessToken() {
 		return this.accessToken;
 	}
 
+	/**
+	 * Returns the DPoP Proof {@link Jwt}.
+	 * @return the DPoP Proof {@link Jwt}
+	 */
 	public String getDPoPProof() {
 		return this.dPoPProof;
 	}
 
+	/**
+	 * Returns the value of the HTTP method of the request.
+	 * @return the value of the HTTP method of the request
+	 */
 	public String getMethod() {
 		return this.method;
 	}
 
+	/**
+	 * Returns the value of the HTTP resource URI of the request, without query and
+	 * fragment parts.
+	 * @return the value of the HTTP resource URI of the request
+	 */
 	public String getResourceUri() {
 		return this.resourceUri;
 	}