1、简介 {#1简介}

Spring Authorization Server（授权服务器）自带一系列合理的默认设置，开箱即用。

但是，它还有一个功能，默认下没有启动：态客户端注册。本文将带你了解如何在客户端应用中启用和使用它。

2、为什么使用动态注册？ {#2为什么使用动态注册}

当基于 OAuth2 的客户端应用（在 OIDC 术语中称为依赖方）启动认证流程时，它将自己的客户端标识符发送给身份提供者（Provider）。

一般情况下，这个标识符是通过外部流程（如邮件发送等其他手段）发放给客户端的，客户端随后将其添加到配置中，并在需要时使用。

例如，在使用 Azure 的 EntraID 或 Auth0 等流行的身份提供商（Identity Provider）解决方案时，我们可以使用管理控制台或 API 来配置新客户端。在此过程中，我们需要告知应用名称、授权回调 URL、支持的作用域等信息。

提供所需信息后，我们会得到一个新的客户端标识符，对于所谓的 "secret" 客户端，还将得到一个 client secret。然后，我们将这些信息添加到应用的配置中，就可以开始部署了。

现在，当我们应用不多，或者总是使用单一的一个身份供应商时（Identity Provider），这种方式就能正常工作。但对于更复杂的情况，注册过程需要是动态的，这就是 OpenID Connect 动态客户端注册规范 的用武之地。

在现实世界中，英国的 OpenBanking 标准就是一个很好的例子，该标准将动态客户注册作为其核心协议之一。

3、动态注册是如何实现的？ {#3动态注册是如何实现的}

OpenID Connect 标准使用一个注册 URL，客户端使用该 URL 注册自己。注册是通过 POST 请求完成的，该请求包含一个 JSON 对象，其中有执行注册所需的客户端元数据。

重要的是，访问注册端点需要身份认证，通常是一个 Bearer Token。当然，这就引出了一个问题：想成为客户端的人如何获得用于此操作的 Token？

遗憾的是，答案并不明确。一方面，规范指出端点是受保护的资源，因此需要某种形式的身份认证。另一方面，它也提到了开放注册端点的可能性。

对于 Spring 授权服务器来说，注册需要一个具有 client.create scope 的 Bearer Token。要创建该令牌，我们需要使用常规 OAuth2 的 Token 端点和基本凭证。

动态注册的流程如下：

客户端注册成功后，就可以使用返回的客户端 ID 和 secret secret 执行任何标准授权流程。

4、实现动态注册 {#4实现动态注册}

了解了所需的步骤后，让我们使用两个 Spring Boot 应用创建一个测试场景。一个托管 Spring 授权服务器，另一个是一个简单的 WebMVC 应用程序，它使用 Spring Security Outh2 Login Starter 模块。

我们先从服务器开始。

5、授权服务器的实现 {#5授权服务器的实现}

首先添加所需的 Maven 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-authorization-server</artifactId>
    <version>1.3.1</version>
</dependency>

最新版本可从 Maven Central 获取。

对于普通的 Spring Authorization Server 来说，只需要这个依赖。

出于安全考虑，默认情况下不会启用动态注册。此外，截至本文撰写时，还 无法通过配置属性来启用动态注册，这意味着我们要通过一些代码来进行配置。

5.1、启用动态注册 {#51启用动态注册}

OAuth2AuthorizationServerConfigurer 是配置授权服务器所有方面的入口，包括注册端点。这个配置应该作为创建 SecurityFilterChain Bean 的一部分完成：

@Configuration
@EnableConfigurationProperties(SecurityConfig.RegistrationProperties.class)
public class SecurityConfig {
    @Bean
    @Order(1)
    public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
        OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
        http.getConfigurer(OAuth2AuthorizationServerConfigurer.class)
          .oidc(oidc -> {
              oidc.clientRegistrationEndpoint(Customizer.withDefaults());
          });

        http.exceptionHandling((exceptions) -> exceptions
          .defaultAuthenticationEntryPointFor(
            new LoginUrlAuthenticationEntryPoint("/login"),
            new MediaTypeRequestMatcher(MediaType.TEXT_HTML)
          )
        );

        http.oauth2ResourceServer((resourceServer) -> resourceServer
            .jwt(Customizer.withDefaults()));

        return http.build();
    }

    // 。。。 其他 Bean
}

如上，我们使用 OAuth2AuthorizationServerConfigurer 的 oidc() 方法来访问 OidConfigurer 实例，该方法允许我们控制与 OpenID Connect 标准相关的端点。要启用注册端点，我们使用带有默认配置的 clientRegistrationEndpoint() 方法。这将在 /connect/register 路径下启用注册端点，并使用 Bearer Token 授权。其他配置选项包括：

• 定义自定义认证
• 对收到的注册数据进行自定义处理
• 对发送给客户端的响应进行自定义处理

现在，由于我们提供的是自定义的 SecurityFilterChain，Spring Boot 默认的自动配置将不会生效，我们需要负责向配置中添加一些额外的部分。

尤其需要添加设置表单登录身份认证的逻辑：

@Bean
@Order(2)
SecurityFilterChain loginFilterChain(HttpSecurity http) throws Exception {
    return http.authorizeHttpRequests(r -> r.anyRequest().authenticated())
      .formLogin(Customizer.withDefaults())
      .build();
}

5.2、注册客户端配置 {#52注册客户端配置}

如上所述，注册机制本身要求客户端发送一个 Bearer Token。Spring 授权服务器要求客户端使用客户端凭证流（Client Credentials Flow）来生成该 Token，从而解决了这个先有鸡还是先有蛋的问题。

此 Token 请求所需的 scope 是 client.create，客户端必须使用服务器支持的认证方案之一。在这里，我们使用 Basic 凭证，但在实际场景中，我们也可以使用其他方法。

从授权服务器的角度来看，这个注册客户端只是另一个客户端。因此，我们使用 RegisteredClient Fluent API 来创建它：

@Bean
public RegisteredClientRepository registeredClientRepository(RegistrationProperties props) {
    RegisteredClient registrarClient = RegisteredClient.withId(UUID.randomUUID().toString())
      .clientId(props.getRegistrarClientId())
      .clientSecret(props.getRegistrarClientSecret())
      .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
      .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS)
      .clientSettings(ClientSettings.builder()
        .requireProofKey(false)
        .requireAuthorizationConsent(false)
        .build())
      .scope("client.create")
      .scope("client.read")
      .build();

    RegisteredClientRepository delegate = new  InMemoryRegisteredClientRepository(registrarClient);
    return new CustomRegisteredClientRepository(delegate);
}

我们使用 @ConfigurationProperties 类允许使用 Spring 的 Environment 来配置 client ID 和 secret 属性。

5.3、自定义 RegisteredClientRepository {#53自定义-registeredclientrepository}

Spring 授权服务器使用配置的 RegisteredClientRepository 实现将所有注册客户端存储在服务器中。开箱即用的是基于内存和 JDBC 的实现，涵盖了基本用例。

然而，这些实现在保存注册信息之前并没有提供任何自定义的能力。在我们的案例中，我们希望修改默认的 ClientProperties 设置，这样在授权用户时就不需要 Consent 或 PKCE。

我们的实现将大多数方法委托给构建时传递的实际 Repository。重要的例外是 save() 方法：

@Override
public void save(RegisteredClient registeredClient) {
    Set<String> scopes = ( registeredClient.getScopes() == null || registeredClient.getScopes().isEmpty())?
      Set.of("openid","email","profile"):
      registeredClient.getScopes();

    // 禁用 PKCE 和 Consent
    RegisteredClient modifiedClient = RegisteredClient.from(registeredClient)
      .scopes(s -> s.addAll(scopes))
      .clientSettings(ClientSettings
        .withSettings(registeredClient.getClientSettings().getSettings())
        .requireAuthorizationConsent(false)
        .requireProofKey(false)
        .build())
      .build();

    delegate.save(modifiedClient);
}

如上，我们根据接收到的 RegisteredClient 创建一个新的 RegisteredClient，并根据需要更改客户端设置。然后，新注册的客户端将被传递到后台，并在需要时存储起来。

至此，服务器的实现就结束了。现在，开始客户端部分。

6、动态注册客户端的实现 {#6动态注册客户端的实现}

我们的客户端也是一个标准的 Spring Web MVC 应用，只有一个页面显示当前用户信息。

Spring Security，或者更具体地说，其 OAuth2 Login 模块，将处理所有安全方面的问题。

从所需的 Maven 依赖开始：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
    <version>3.3.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
    <version>3.3.2</version>
</dependency>

这些依赖的最新版本可从 Maven Central 获取：

• spring-boot-starter-web
• spring-boot-starter-thymeleaf
• spring-boot-starter-oauth2-client

6.1、Security 配置 {#61security-配置}

默认情况下，Spring Boot 的自动配置机制使用来自可用 PropertySources 的信息来收集所需数据，以创建一个或多个 ClientRegistration 实例，然后将其存储在基于内存的 ClientRegistrationRepository 中。

例如，给定的 application.yaml 如下：

spring:
  security:
    oauth2:
      client:
        provider:
          spring-auth-server:
            issuer-uri: http://localhost:8080
        registration:
          test-client:
            provider: spring-auth-server
            client-name: test-client
            client-id: xxxxx
            client-secret: yyyy
            authorization-grant-type:
              - authorization_code
              - refresh_token
              - client_credentials
            scope:
              - openid
              - email
              - profile

Spring 将创建名为 test-client 的 ClientRegistration 并将其传递给 Repository。

之后，当需要启动身份认证流程时，OAuth2 引擎就会查询该 Repository，并根据其注册标识符（在我们的例子中为 test-client）恢复注册信息。

这里的关键点是，授权服务器应该已经知道此时返回的 ClientRegistration。这意味着，为了支持动态客户端，我们必须实现一个替代 Repository，并将其作为 @Bean 暴露。

这样，Spring Boot 的自动配置就会自动使用它，而不是默认配置。

6.2、动态 ClientRegistration Repository {#62动态-clientregistration-repository}

我们必须实现 ClientRegistration 接口，而该接口只包含一个方法：findByRegistrationId()。这就有一个问题： OAuth2 引擎如何知道哪些注册信息是可用的？毕竟，它可以在默认登录页面上列出这些注册信息。

事实证明，Spring Security 也希望 Repository 也能实现 Iterable<ClientRegistration>，这样它就能枚举可用的客户端：

public class DynamicClientRegistrationRepository implements ClientRegistrationRepository, Iterable<ClientRegistration> {
    private final RegistrationDetails registrationDetails;
    private final Map<String, ClientRegistration> staticClients;
    private final RegistrationRestTemplate registrationClient;
    private final Map<String, ClientRegistration> registrations = new HashMap<>();

    // 实现省略。。。
}

该类需要一些关键属性才可以运行：

• 一个 RegistrationDetails，其中包含执行动态注册所需的所有参数
• 存储动态注册的 ClientRegistration 的 Map。
• 用于访问授权服务器的 RestTemplate。

注意，在本例中，我们假设所有客户端都在同一授权服务器上进行注册。

另一个重要的设计决策是定义何时进行动态注册。这里，我们采取一种简单的方法，公开 doRegistrations() 方法，该方法将注册所有已知客户端，并保存返回的客户端标识符和 secret，以供以后使用：

public void doRegistrations() {
    staticClients.forEach((key, value) -> findByRegistrationId(key));
}

对于传递给构造函数的每个 staticClients ，实现过程都会调用 findByRegistrationId()。该方法会检查给定标识符是否存在有效注册，如果没有，则会触发实际注册流程。

6.3、动态注册 {#63动态注册}

doRegistration() 函数才是真正发挥作用的地方：

private ClientRegistration doRegistration(String registrationId) {
    String token = createRegistrationToken();
    var staticRegistration = staticClients.get(registrationId);

    var body = Map.of(
      "client_name", staticRegistration.getClientName(),
      "grant_types", List.of(staticRegistration.getAuthorizationGrantType()),
      "scope", String.join(" ", staticRegistration.getScopes()),
      "redirect_uris", List.of(resolveCallbackUri(staticRegistration)));

    var headers = new HttpHeaders();
    headers.setBearerAuth(token);
    headers.setContentType(MediaType.APPLICATION_JSON);

    var request = new RequestEntity<>(
      body,
      headers,
      HttpMethod.POST,
      registrationDetails.registrationEndpoint());

    var response = registrationClient.exchange(request, ObjectNode.class);
    // ... 省略异常处理
    return createClientRegistration(staticRegistration, response.getBody());
}

首先，我们必须获取调用注册端点所需的注册 Token。注意，我们必须为每次注册尝试获取一个新 Token，因为正如 Spring Authorization 的服务器文档所述，我们只能使用该 Token 一次。

接下来，使用静态注册对象中的数据构建注册 Payload，添加所需的 authorization 和 content-type Header，然后将请求发送到注册端点。

最后，使用响应数据创建最终的 ClientRegistration，并将其保存在 Repository 的缓存中，然后返回给 OAuth2 引擎。

6.4、注册 ClientRegistrationRepository @Bean {#64注册-clientregistrationrepository-bean}

完成客户端的最后一步是将 DynamicClientRegistrationRepository 作为 @Bean 公开。

创建一个 @Configuration 类：

@Bean
ClientRegistrationRepository dynamicClientRegistrationRepository( DynamicClientRegistrationRepository.RegistrationRestTemplate restTemplate) {
    var registrationDetails = new DynamicClientRegistrationRepository.RegistrationDetails(
      registrationProperties.getRegistrationEndpoint(),
      registrationProperties.getRegistrationUsername(),
      registrationProperties.getRegistrationPassword(),
      registrationProperties.getRegistrationScopes(),
      registrationProperties.getGrantTypes(),
      registrationProperties.getRedirectUris(),
      registrationProperties.getTokenEndpoint());

    Map<String,ClientRegistration> staticClients = (new OAuth2ClientPropertiesMapper(clientProperties)).asClientRegistrations();
    var repo =  new DynamicClientRegistrationRepository(registrationDetails, staticClients, restTemplate);
    repo.doRegistrations();
    return repo;
}

@Bean 注解的 dynamicClientRegistrationRepository() 方法首先会根据可用属性填充 RegistrationDetails 记录，从而创建 Repository。

其次，它利用 Spring Boot 自动配置模块中的 OAuth2ClientPropertiesMapper 类创建 staticClient map。由于两者的配置结构相同，因此这种方法能让我们以最小的工作量快速从静态客户端（staticClients）切换到动态客户端，然后再切换回来。

7、测试 {#7测试}

最后，进行一些集成测试。首先，启动服务器应用，将其配置为监听 8080 端口：

[ server ] $ mvn spring-boot:run
... lots of messages omitted
[           main] c.b.s.s.a.AuthorizationServerApplication : Started AuthorizationServerApplication in 2.222 seconds (process running for 2.454)
[           main] o.s.b.a.ApplicationAvailabilityBean      : Application availability state LivenessState changed to CORRECT
[           main] o.s.b.a.ApplicationAvailabilityBean      : Application availability state ReadinessState changed to ACCEPTING_TRAFFIC

接下来，在另一个 shell 中启动客户端：

[client] $ mvn spring-boot:run
// ... 省略其他消息
[  restartedMain] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
[  restartedMain] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8090 (http) with context path ''
[  restartedMain] d.c.DynamicRegistrationClientApplication : Started DynamicRegistrationClientApplication in 2.063 seconds (process running for 2.425)

这两个应用在运行时都设置了 debug 属性，因此会产生大量日志信息。重点是，我们可以看到对授权服务器 /connect/register 端点的调用：

[nio-8080-exec-3] o.s.security.web.FilterChainProxy        : Securing POST /connect/register
// ... lots of messages omitted
[nio-8080-exec-3] ClientRegistrationAuthenticationProvider : Retrieved authorization with initial access token
[nio-8080-exec-3] ClientRegistrationAuthenticationProvider : Validated client registration request parameters
[nio-8080-exec-3] s.s.a.r.CustomRegisteredClientRepository : Saving registered client: id=30OTlhO1Fb7UF110YdXULEDbFva4Uc8hPBGMfi60Wik, name=test-client

在客户端，我们可以看到一条包含注册标识符（test-client ）和相应 client_id 的信息：

[  restartedMain] s.d.c.c.OAuth2DynamicClientConfiguration : Creating a dynamic client registration repository
[  restartedMain] .c.s.DynamicClientRegistrationRepository : findByRegistrationId: test-client
[  restartedMain] .c.s.DynamicClientRegistrationRepository : doRegistration: registrationId=test-client
[  restartedMain] .c.s.DynamicClientRegistrationRepository : creating ClientRegistration: registrationId=test-client, client_id=30OTlhO1Fb7UF110YdXULEDbFva4Uc8hPBGMfi60Wik

如果我们打开浏览器并访问 http://localhost:8090 ，就会被重定向到登录页面。注意，地址栏中的 URL 变成了 http://localhost:8080，这表明该页面来自授权服务器。

测试凭证为 user1/password。将其填入表单并发送后，就会返回客户端主页。由于我们现在已通过身份认证，我们可以看到一个页面，其中包含从 Authorization Token 中提取的一些详细信息。

8、总结 {#8总结}

本文介绍了如何启用 Spring Authorization Server 的动态注册功能，并在基于 Spring Security 的客户端应用中使用该功能。

Ref：https://www.baeldung.com/spring-dynamic-client-registration