Add comments

Author: ReLive27

device-authorization-flow/device-authorization-server/src/main/java/com/relive/authentication/DeviceClientAuthenticationConverter.java

@@ -21,46 +21,94 @@
 import java.util.Map;
 
 /**
+ * {@code DeviceClientAuthenticationConverter} 类实现了 {@link AuthenticationConverter} 接口，
+ * 用于将设备授权请求或设备访问令牌请求转换为 {@link DeviceClientAuthenticationToken} 实例。
+ *
+ * <p>它主要处理以下两类请求：</p>
+ * <ul>
+ *     <li>设备授权请求（包含 "device_code" 参数）。</li>
+ *     <li>设备访问令牌请求（包含 "grant_type=device_code" 和 "device_code" 参数）。</li>
+ * </ul>
+ *
+ * <p>该转换器对请求参数进行严格验证，如校验 client_id 是否唯一且有效。</p>
+ *
  * @author: ReLive27
  * @date: 2024/1/23 22:43
  */
 public class DeviceClientAuthenticationConverter implements AuthenticationConverter {
+
+    /**
+     * 匹配设备授权请求的条件。
+     */
     private final RequestMatcher deviceAuthorizationRequestMatcher;
+
+    /**
+     * 匹配设备访问令牌请求的条件。
+     */
     private final RequestMatcher deviceAccessTokenRequestMatcher;
 
+    /**
+     * 构造函数，初始化请求匹配器。
+     *
+     * @param deviceAuthorizationEndpointUri 设备授权端点的 URI，用于匹配设备授权请求。
+     */
     public DeviceClientAuthenticationConverter(String deviceAuthorizationEndpointUri) {
+        // 匹配设备授权请求：路径匹配、响应类型为 device_code 且包含 client_id 参数
         this.deviceAuthorizationRequestMatcher = new AndRequestMatcher(
                 new AntPathRequestMatcher(
                         deviceAuthorizationEndpointUri, HttpMethod.POST.name()),
                 request -> "device_code".equals(request.getParameter(OAuth2ParameterNames.RESPONSE_TYPE)),
                 request -> request.getParameter(OAuth2ParameterNames.CLIENT_ID) != null);
+
+        // 匹配设备访问令牌请求：grant_type 为 device_code，且包含 device_code 和 client_id 参数
         this.deviceAccessTokenRequestMatcher = request ->
                 AuthorizationGrantType.DEVICE_CODE.getValue().equals(request.getParameter(OAuth2ParameterNames.GRANT_TYPE)) &&
                         request.getParameter(OAuth2ParameterNames.DEVICE_CODE) != null &&
                         request.getParameter(OAuth2ParameterNames.CLIENT_ID) != null;
     }
 
+    /**
+     * 转换请求为 {@link DeviceClientAuthenticationToken}。
+     *
+     * @param request 当前的 HTTP 请求。
+     * @return 如果请求匹配设备授权或设备访问令牌请求，返回一个 {@link DeviceClientAuthenticationToken}，否则返回 {@code null}。
+     * @throws OAuth2AuthenticationException 如果请求参数无效（如缺少或多于一个 client_id）。
+     */
     @Nullable
     @Override
     public Authentication convert(HttpServletRequest request) {
+        // 请求不匹配设备授权请求或设备访问令牌请求，返回 null
         if (!this.deviceAuthorizationRequestMatcher.matches(request) &&
                 !this.deviceAccessTokenRequestMatcher.matches(request)) {
             return null;
         }
 
-        // client_id (REQUIRED)
+        // 提取 client_id，确保非空且唯一
         String clientId = request.getParameter(OAuth2ParameterNames.CLIENT_ID);
         if (!StringUtils.hasText(clientId) ||
                 request.getParameterValues(OAuth2ParameterNames.CLIENT_ID).length != 1) {
             throw new OAuth2AuthenticationException(OAuth2ErrorCodes.INVALID_REQUEST);
         }
+
+        // 提取额外的请求参数，排除 client_id 参数
         Map<String, Object> additionalParameters = getParametersIfMatchesDeviceCodeGrantRequest(request,
                 OAuth2ParameterNames.CLIENT_ID);
+
+        // 返回一个新的 DeviceClientAuthenticationToken 实例
         return new DeviceClientAuthenticationToken(clientId, ClientAuthenticationMethod.NONE, null, additionalParameters);
     }
 
+    /**
+     * 提取请求中的参数，排除指定的参数名（如 client_id）。
+     *
+     * @param request    当前的 HTTP 请求。
+     * @param exclusions 要排除的参数名。
+     * @return 返回一个包含请求参数的 Map，排除了指定的参数。
+     */
     static Map<String, Object> getParametersIfMatchesDeviceCodeGrantRequest(HttpServletRequest request, String... exclusions) {
         MultiValueMap<String, String> multiValueParameters = getParameters(request);
+
+        // 排除指定的参数
         for (String exclusion : exclusions) {
             multiValueParameters.remove(exclusion);
         }
@@ -72,17 +120,24 @@ static Map<String, Object> getParametersIfMatchesDeviceCodeGrantRequest(HttpServ
         return parameters;
     }
 
+    /**
+     * 提取请求中的所有参数，并返回为 {@link MultiValueMap}。
+     *
+     * @param request 当前的 HTTP 请求。
+     * @return 包含请求参数的 {@link MultiValueMap}。
+     */
     static MultiValueMap<String, String> getParameters(HttpServletRequest request) {
         Map<String, String[]> parameterMap = request.getParameterMap();
         MultiValueMap<String, String> parameters = new LinkedMultiValueMap<>(parameterMap.size());
+
         parameterMap.forEach((key, values) -> {
             if (values.length > 0) {
                 for (String value : values) {
                     parameters.add(key, value);
                 }
             }
         });
+
         return parameters;
     }
 }
-

device-authorization-flow/device-authorization-server/src/main/java/com/relive/authentication/DeviceClientAuthenticationProvider.java

@@ -14,34 +14,67 @@
 import org.springframework.util.Assert;
 
 /**
+ * {@code DeviceClientAuthenticationProvider} 实现了 {@link AuthenticationProvider} 接口，
+ * 用于验证设备授权客户端的身份（无客户端凭证，基于 client_id）。
+ *
+ * <p>该 Provider 支持以下功能：</p>
+ * <ul>
+ *     <li>校验客户端认证方法是否为 {@code none}（无认证）。</li>
+ *     <li>验证 client_id 是否存在并匹配已注册客户端。</li>
+ *     <li>确保客户端支持无认证方法 {@link ClientAuthenticationMethod#NONE}。</li>
+ * </ul>
+ *
+ * <p>如果验证失败，则会抛出 {@link OAuth2AuthenticationException} 异常，错误信息符合 RFC 6749 标准。</p>
+ *
  * @author: ReLive27
  * @date: 2024/1/23 22:41
  */
 @Slf4j
 public class DeviceClientAuthenticationProvider implements AuthenticationProvider {
+
     private static final String ERROR_URI = "https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1";
+
+    /**
+     * 客户端注册仓库，用于查找已注册的客户端。
+     */
     private final RegisteredClientRepository registeredClientRepository;
 
+    /**
+     * 构造函数，初始化 {@link RegisteredClientRepository}。
+     *
+     * @param registeredClientRepository 客户端注册仓库，不能为 {@code null}。
+     */
     public DeviceClientAuthenticationProvider(RegisteredClientRepository registeredClientRepository) {
         Assert.notNull(registeredClientRepository, "registeredClientRepository cannot be null");
         this.registeredClientRepository = registeredClientRepository;
     }
 
+    /**
+     * 对设备客户端认证请求进行身份验证。
+     *
+     * @param authentication 设备客户端认证请求，包含 {@code client_id} 和认证方法。
+     * @return 如果验证成功，返回新的 {@link DeviceClientAuthenticationToken} 实例；
+     * 如果认证方法不支持，返回 {@code null}。
+     * @throws OAuth2AuthenticationException 如果验证失败（如 {@code client_id} 无效或不支持的认证方法）。
+     */
     @Override
     public Authentication authenticate(Authentication authentication) throws AuthenticationException {
         DeviceClientAuthenticationToken deviceClientAuthentication =
                 (DeviceClientAuthenticationToken) authentication;
 
+        // 仅支持无客户端认证方法（none）
         if (!ClientAuthenticationMethod.NONE.equals(deviceClientAuthentication.getClientAuthenticationMethod())) {
             return null;
         }
 
+        // 校验 client_id
         String clientId = deviceClientAuthentication.getPrincipal().toString();
         RegisteredClient registeredClient = this.registeredClientRepository.findByClientId(clientId);
         if (registeredClient == null) {
             throwInvalidClient(OAuth2ParameterNames.CLIENT_ID);
         }
 
+        // 校验客户端是否支持 "none" 认证方法
         if (!registeredClient.getClientAuthenticationMethods().contains(
                 deviceClientAuthentication.getClientAuthenticationMethod())) {
             throwInvalidClient("authentication_method");
@@ -51,19 +84,27 @@ public Authentication authenticate(Authentication authentication) throws Authent
             log.trace("Validated device client authentication parameters");
         }
 
-        if (log.isTraceEnabled()) {
-            log.trace("Authenticated device client");
-        }
-
         return new DeviceClientAuthenticationToken(registeredClient,
                 deviceClientAuthentication.getClientAuthenticationMethod(), null);
     }
 
+    /**
+     * 确定是否支持指定的认证类型。
+     *
+     * @param authentication 认证类型。
+     * @return 如果支持 {@link DeviceClientAuthenticationToken} 类型，返回 {@code true}。
+     */
     @Override
     public boolean supports(Class<?> authentication) {
         return DeviceClientAuthenticationToken.class.isAssignableFrom(authentication);
     }
 
+    /**
+     * 抛出无效客户端异常，附带错误描述和 URI 链接。
+     *
+     * @param parameterName 失败的具体参数（如 {@code client_id} 或认证方法）。
+     * @throws OAuth2AuthenticationException 包装的 OAuth2 错误。
+     */
     private static void throwInvalidClient(String parameterName) {
         OAuth2Error error = new OAuth2Error(
                 OAuth2ErrorCodes.INVALID_CLIENT,
@@ -72,5 +113,4 @@ private static void throwInvalidClient(String parameterName) {
         );
         throw new OAuth2AuthenticationException(error);
     }
-
 }

device-authorization-flow/device-authorization-server/src/main/java/com/relive/authentication/DeviceClientAuthenticationToken.java

@@ -8,19 +8,50 @@
 import java.util.Map;
 
 /**
+ * {@code DeviceClientAuthenticationToken} 是设备客户端身份验证的自定义令牌。
+ *
+ * <p>该类继承自 {@link OAuth2ClientAuthenticationToken}，主要用于 OAuth 2.0 设备授权流程中的客户端认证。</p>
+ *
+ * <p>设备客户端身份验证的特点：</p>
+ * <ul>
+ *     <li>客户端不需要使用客户端密钥（即无凭证认证）。</li>
+ *     <li>认证过程中必须提供 {@code client_id}。</li>
+ *     <li>可能包含额外参数 {@link Map}，例如设备授权请求中的信息。</li>
+ * </ul>
+ *
+ * <p>该类提供两种构造函数：</p>
+ * <ul>
+ *     <li>一种基于 {@code clientId} 和认证方法（适用于请求阶段）。</li>
+ *     <li>一种基于已注册客户端 {@link RegisteredClient}（适用于验证通过后的阶段）。</li>
+ * </ul>
+ *
  * @author: ReLive27
  * @date: 2024/1/23 22:42
  */
 public class DeviceClientAuthenticationToken extends OAuth2ClientAuthenticationToken {
 
+    /**
+     * 构造函数。
+     *
+     * @param clientId                   客户端 ID，表示发起请求的客户端。
+     * @param clientAuthenticationMethod 客户端认证方法，通常为 {@link ClientAuthenticationMethod#NONE}。
+     * @param credentials                凭据，可以为 {@code null}。
+     * @param additionalParameters       额外参数，例如设备授权请求中的参数，允许为 {@code null}。
+     */
     public DeviceClientAuthenticationToken(String clientId, ClientAuthenticationMethod clientAuthenticationMethod,
                                            @Nullable Object credentials, @Nullable Map<String, Object> additionalParameters) {
         super(clientId, clientAuthenticationMethod, credentials, additionalParameters);
     }
 
+    /**
+     * 构造函数，用于基于已注册客户端创建。
+     *
+     * @param registeredClient           已注册客户端，表示通过验证的客户端。
+     * @param clientAuthenticationMethod 客户端认证方法，通常为 {@link ClientAuthenticationMethod#NONE}。
+     * @param credentials                凭据，可以为 {@code null}。
+     */
     public DeviceClientAuthenticationToken(RegisteredClient registeredClient, ClientAuthenticationMethod clientAuthenticationMethod,
                                            @Nullable Object credentials) {
         super(registeredClient, clientAuthenticationMethod, credentials);
     }
-
 }