操作指南：動態客戶端註冊

本指南展示瞭如何在 Spring Authorization Server 中配置 OpenID Connect 動態客戶端註冊，並透過示例講解如何註冊客戶端。Spring Authorization Server 實現了 OpenID Connect Dynamic Client Registration 1.0 規範，提供了動態註冊和檢索 OpenID Connect 客戶端的功能。

啟用動態客戶端註冊
配置客戶端註冊器
獲取初始訪問令牌
註冊客戶端

啟用動態客戶端註冊

預設情況下，Spring Authorization Server 中的動態客戶端註冊功能是停用的。要啟用，請新增以下配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.oauth2.server.authorization.config.annotation.web.configurers.OAuth2AuthorizationServerConfigurer;
import org.springframework.security.web.SecurityFilterChain;

import static sample.registration.CustomClientMetadataConfig.configureCustomClientMetadataConverters;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
		OAuth2AuthorizationServerConfigurer authorizationServerConfigurer =
				OAuth2AuthorizationServerConfigurer.authorizationServer();

		http
			.securityMatcher(authorizationServerConfigurer.getEndpointsMatcher())
			.with(authorizationServerConfigurer, (authorizationServer) ->
				authorizationServer
					.oidc((oidc) ->
						oidc.clientRegistrationEndpoint((clientRegistrationEndpoint) ->	(1)
							clientRegistrationEndpoint
								.authenticationProviders(configureCustomClientMetadataConverters())	(2)
						)
					)
			)
			.authorizeHttpRequests((authorize) ->
				authorize
					.anyRequest().authenticated()
			);

		return http.build();
	}

}

1	使用預設配置啟用 OpenID Connect 1.0 客戶端註冊端點。
2	可選地，自定義預設的 `AuthenticationProvider` 以支援自定義客戶端元資料引數。

為了在註冊客戶端時支援自定義客戶端元資料引數，還需要一些額外的實現細節。

以下示例展示了支援自定義客戶端元資料引數（logo_uri 和 contacts）並在 OidcClientRegistrationAuthenticationProvider 和 OidcClientConfigurationAuthenticationProvider 中配置的 Converter 示例實現。

import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.stream.Collectors;

import org.springframework.core.convert.converter.Converter;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
import org.springframework.security.oauth2.server.authorization.oidc.OidcClientRegistration;
import org.springframework.security.oauth2.server.authorization.oidc.authentication.OidcClientConfigurationAuthenticationProvider;
import org.springframework.security.oauth2.server.authorization.oidc.authentication.OidcClientRegistrationAuthenticationProvider;
import org.springframework.security.oauth2.server.authorization.oidc.converter.OidcClientRegistrationRegisteredClientConverter;
import org.springframework.security.oauth2.server.authorization.oidc.converter.RegisteredClientOidcClientRegistrationConverter;
import org.springframework.security.oauth2.server.authorization.settings.ClientSettings;
import org.springframework.util.CollectionUtils;

public class CustomClientMetadataConfig {

	public static Consumer<List<AuthenticationProvider>> configureCustomClientMetadataConverters() {	(1)
		List<String> customClientMetadata = List.of("logo_uri", "contacts");	(2)

		return (authenticationProviders) -> {
			CustomRegisteredClientConverter registeredClientConverter =
					new CustomRegisteredClientConverter(customClientMetadata);
			CustomClientRegistrationConverter clientRegistrationConverter =
					new CustomClientRegistrationConverter(customClientMetadata);

			authenticationProviders.forEach((authenticationProvider) -> {
				if (authenticationProvider instanceof OidcClientRegistrationAuthenticationProvider provider) {
					provider.setRegisteredClientConverter(registeredClientConverter);	(3)
					provider.setClientRegistrationConverter(clientRegistrationConverter);	(4)
				}
				if (authenticationProvider instanceof OidcClientConfigurationAuthenticationProvider provider) {
					provider.setClientRegistrationConverter(clientRegistrationConverter);	(5)
				}
			});
		};
	}

	private static class CustomRegisteredClientConverter
			implements Converter<OidcClientRegistration, RegisteredClient> {

		private final List<String> customClientMetadata;
		private final OidcClientRegistrationRegisteredClientConverter delegate;

		private CustomRegisteredClientConverter(List<String> customClientMetadata) {
			this.customClientMetadata = customClientMetadata;
			this.delegate = new OidcClientRegistrationRegisteredClientConverter();
		}

		@Override
		public RegisteredClient convert(OidcClientRegistration clientRegistration) {
			RegisteredClient registeredClient = this.delegate.convert(clientRegistration);
			ClientSettings.Builder clientSettingsBuilder = ClientSettings.withSettings(
					registeredClient.getClientSettings().getSettings());
			if (!CollectionUtils.isEmpty(this.customClientMetadata)) {
				clientRegistration.getClaims().forEach((claim, value) -> {
					if (this.customClientMetadata.contains(claim)) {
						clientSettingsBuilder.setting(claim, value);
					}
				});
			}

			return RegisteredClient.from(registeredClient)
					.clientSettings(clientSettingsBuilder.build())
					.build();
		}
	}

	private static class CustomClientRegistrationConverter
			implements Converter<RegisteredClient, OidcClientRegistration> {

		private final List<String> customClientMetadata;
		private final RegisteredClientOidcClientRegistrationConverter delegate;

		private CustomClientRegistrationConverter(List<String> customClientMetadata) {
			this.customClientMetadata = customClientMetadata;
			this.delegate = new RegisteredClientOidcClientRegistrationConverter();
		}

		@Override
		public OidcClientRegistration convert(RegisteredClient registeredClient) {
			OidcClientRegistration clientRegistration = this.delegate.convert(registeredClient);
			Map<String, Object> claims = new HashMap<>(clientRegistration.getClaims());
			if (!CollectionUtils.isEmpty(this.customClientMetadata)) {
				ClientSettings clientSettings = registeredClient.getClientSettings();
				claims.putAll(this.customClientMetadata.stream()
						.filter(metadata -> clientSettings.getSetting(metadata) != null)
						.collect(Collectors.toMap(Function.identity(), clientSettings::getSetting)));
			}

			return OidcClientRegistration.withClaims(claims).build();
		}

	}

}

1	定義一個 `Consumer<List<AuthenticationProvider>>`，提供自定義預設 `AuthenticationProvider` 的能力。
2	定義客戶端註冊支援的自定義客戶端元資料引數。
3	使用 `CustomRegisteredClientConverter` 配置 `OidcClientRegistrationAuthenticationProvider.setRegisteredClientConverter()`。
4	使用 `CustomClientRegistrationConverter` 配置 `OidcClientRegistrationAuthenticationProvider.setClientRegistrationConverter()`。
5	使用 `CustomClientRegistrationConverter` 配置 `OidcClientConfigurationAuthenticationProvider.setClientRegistrationConverter()`。

配置客戶端註冊器

使用現有客戶端向授權伺服器註冊新客戶端。該客戶端必須配置 client.create 範圍（用於註冊客戶端）和可選的 client.read 範圍（用於檢索客戶端）。以下列表顯示了一個示例客戶端

import java.util.UUID;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.core.AuthorizationGrantType;
import org.springframework.security.oauth2.core.ClientAuthenticationMethod;
import org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository;
import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository;

@Configuration
public class ClientConfig {

	@Bean
	public RegisteredClientRepository registeredClientRepository() {
		RegisteredClient registrarClient = RegisteredClient.withId(UUID.randomUUID().toString())
				.clientId("registrar-client")
				.clientSecret("{noop}secret")
				.clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
				.authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS)	(1)
				.scope("client.create")	(2)
				.scope("client.read")	(3)
				.build();

		return new InMemoryRegisteredClientRepository(registrarClient);
	}

}

1	配置了 `client_credentials` grant type 以直接獲取訪問令牌。
2	配置了 `client.create` 範圍，允許客戶端註冊新客戶端。
3	配置了 `client.read` 範圍，允許客戶端檢索已註冊的客戶端。

獲取初始訪問令牌

客戶端註冊請求需要一個“初始”訪問令牌。訪問令牌請求 **必須** 僅包含 scope 引數值 client.create。

POST /oauth2/token HTTP/1.1
Authorization: Basic <base64-encoded-credentials>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=client.create

客戶端註冊請求需要一個僅包含 client.create 範圍的訪問令牌。如果訪問令牌包含額外的範圍，客戶端註冊請求將被拒絕。

要獲取上述請求的編碼憑據，請將客戶端憑據以 <clientId>:<clientSecret> 的格式進行 base64 編碼。下面是本指南示例的編碼操作。

echo -n "registrar-client:secret" | base64

註冊客戶端

有了上一步獲取的訪問令牌，現在可以動態註冊客戶端了。

“初始”訪問令牌只能使用一次。客戶端註冊後，該訪問令牌將失效。

import java.util.List;
import java.util.Objects;

import com.fasterxml.jackson.annotation.JsonProperty;
import reactor.core.publisher.Mono;

import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.security.oauth2.core.AuthorizationGrantType;
import org.springframework.web.reactive.function.client.WebClient;

public class ClientRegistrar {
	private final WebClient webClient;

	public ClientRegistrar(WebClient webClient) {
		this.webClient = webClient;
	}

	public record ClientRegistrationRequest(	(1)
			@JsonProperty("client_name") String clientName,
			@JsonProperty("grant_types") List<String> grantTypes,
			@JsonProperty("redirect_uris") List<String> redirectUris,
			@JsonProperty("logo_uri") String logoUri,
			List<String> contacts,
			String scope) {
	}

	public record ClientRegistrationResponse(	(2)
			@JsonProperty("registration_access_token") String registrationAccessToken,
			@JsonProperty("registration_client_uri") String registrationClientUri,
			@JsonProperty("client_name") String clientName,
			@JsonProperty("client_id") String clientId,
			@JsonProperty("client_secret") String clientSecret,
			@JsonProperty("grant_types") List<String> grantTypes,
			@JsonProperty("redirect_uris") List<String> redirectUris,
		 	@JsonProperty("logo_uri") String logoUri,
		 	List<String> contacts,
			String scope) {
	}

	public void exampleRegistration(String initialAccessToken) {	(3)
		ClientRegistrationRequest clientRegistrationRequest = new ClientRegistrationRequest(	(4)
				"client-1",
				List.of(AuthorizationGrantType.AUTHORIZATION_CODE.getValue()),
				List.of("https://client.example.org/callback", "https://client.example.org/callback2"),
				"https://client.example.org/logo",
				List.of("contact-1", "contact-2"),
				"openid email profile"
		);

		ClientRegistrationResponse clientRegistrationResponse =
				registerClient(initialAccessToken, clientRegistrationRequest);	(5)

		assert (clientRegistrationResponse.clientName().contentEquals("client-1"));	(6)
		assert (!Objects.isNull(clientRegistrationResponse.clientSecret()));
		assert (clientRegistrationResponse.scope().contentEquals("openid profile email"));
		assert (clientRegistrationResponse.grantTypes().contains(AuthorizationGrantType.AUTHORIZATION_CODE.getValue()));
		assert (clientRegistrationResponse.redirectUris().contains("https://client.example.org/callback"));
		assert (clientRegistrationResponse.redirectUris().contains("https://client.example.org/callback2"));
		assert (!clientRegistrationResponse.registrationAccessToken().isEmpty());
		assert (!clientRegistrationResponse.registrationClientUri().isEmpty());
		assert (clientRegistrationResponse.logoUri().contentEquals("https://client.example.org/logo"));
		assert (clientRegistrationResponse.contacts().size() == 2);
		assert (clientRegistrationResponse.contacts().contains("contact-1"));
		assert (clientRegistrationResponse.contacts().contains("contact-2"));

		String registrationAccessToken = clientRegistrationResponse.registrationAccessToken();	(7)
		String registrationClientUri = clientRegistrationResponse.registrationClientUri();

		ClientRegistrationResponse retrievedClient = retrieveClient(registrationAccessToken, registrationClientUri);	(8)

		assert (retrievedClient.clientName().contentEquals("client-1"));	(9)
		assert (!Objects.isNull(retrievedClient.clientId()));
		assert (!Objects.isNull(retrievedClient.clientSecret()));
		assert (retrievedClient.scope().contentEquals("openid profile email"));
		assert (retrievedClient.grantTypes().contains(AuthorizationGrantType.AUTHORIZATION_CODE.getValue()));
		assert (retrievedClient.redirectUris().contains("https://client.example.org/callback"));
		assert (retrievedClient.redirectUris().contains("https://client.example.org/callback2"));
		assert (retrievedClient.logoUri().contentEquals("https://client.example.org/logo"));
		assert (retrievedClient.contacts().size() == 2);
		assert (retrievedClient.contacts().contains("contact-1"));
		assert (retrievedClient.contacts().contains("contact-2"));
		assert (Objects.isNull(retrievedClient.registrationAccessToken()));
		assert (!retrievedClient.registrationClientUri().isEmpty());
	}

	public ClientRegistrationResponse registerClient(String initialAccessToken, ClientRegistrationRequest request) {	(10)
		return this.webClient
				.post()
				.uri("/connect/register")
				.contentType(MediaType.APPLICATION_JSON)
				.accept(MediaType.APPLICATION_JSON)
				.header(HttpHeaders.AUTHORIZATION, "Bearer %s".formatted(initialAccessToken))
				.body(Mono.just(request), ClientRegistrationRequest.class)
				.retrieve()
				.bodyToMono(ClientRegistrationResponse.class)
				.block();
	}

	public ClientRegistrationResponse retrieveClient(String registrationAccessToken, String registrationClientUri) {	(11)
		return this.webClient
				.get()
				.uri(registrationClientUri)
				.header(HttpHeaders.AUTHORIZATION, "Bearer %s".formatted(registrationAccessToken))
				.retrieve()
				.bodyToMono(ClientRegistrationResponse.class)
				.block();
	}

}

1	客戶端註冊請求的最小表示。您可以根據 Client Registration Request 新增額外的客戶端元資料引數。此示例請求包含自定義客戶端元資料引數 `logo_uri` 和 `contacts`。
2	客戶端註冊響應的最小表示。您可以根據 Client Registration Response 新增額外的客戶端元資料引數。此示例響應包含自定義客戶端元資料引數 `logo_uri` 和 `contacts`。
3	演示客戶端註冊和客戶端檢索的示例。
4	示例客戶端註冊請求物件。
5	使用“初始”訪問令牌和客戶端註冊請求物件註冊客戶端。
6	成功註冊後，對響應中應填充的客戶端元資料引數進行斷言。
7	提取 `registration_access_token` 和 `registration_client_uri` 響應引數，用於檢索新註冊的客戶端。
8	使用 `registration_access_token` 和 `registration_client_uri` 檢索客戶端。
9	客戶端檢索後，對響應中應填充的客戶端元資料引數進行斷言。
10	使用 `WebClient` 的 Client Registration Request 示例。
11	使用 `WebClient` 的 Client Read Request 示例。

Client Read Response 應包含與 Client Registration Response 相同的客戶端元資料引數，但 registration_access_token 引數除外。