此版本仍在开发中，尚未被视为稳定版本。如需最新稳定版本，请使用 Spring Security 7.0.4！spring-doc.cadn.net.cn

核心接口与类

本节介绍 Spring Security 提供的 OAuth2 核心接口和类。spring-doc.cadn.net.cn

客户端注册

ClientRegistration 表示在 OAuth 2.0 或 OpenID Connect 1.0 提供商处注册的客户端。spring-doc.cadn.net.cn

ClientRegistration 对象包含诸如客户端 ID、客户端密钥、授权许可类型、重定向 URI、作用域（scope(s)）、授权 URI、Tokens URI 以及其他详细信息。spring-doc.cadn.net.cn

ClientRegistration 及其属性定义如下：spring-doc.cadn.net.cn

public final class ClientRegistration {
	private String registrationId;	(1)
	private String clientId;	(2)
	private String clientSecret;	(3)
	private ClientAuthenticationMethod clientAuthenticationMethod;	(4)
	private AuthorizationGrantType authorizationGrantType;	(5)
	private String redirectUri;	(6)
	private Set<String> scopes;	(7)
	private ProviderDetails providerDetails;
	private String clientName;	(8)

	public class ProviderDetails {
		private String authorizationUri;	(9)
		private String tokenUri;	(10)
		private UserInfoEndpoint userInfoEndpoint;
		private String jwkSetUri;	(11)
		private String issuerUri;	(12)
        private Map<String, Object> configurationMetadata;  (13)

		public class UserInfoEndpoint {
			private String uri;	(14)
            private AuthenticationMethod authenticationMethod;  (15)
			private String userNameAttributeName;	(16)

		}
	}

	public static final class ClientSettings {
		private boolean requireProofKey; (17)
	}
}
1 registrationId：唯一标识 ClientRegistration 的 ID。
2 clientId：客户端标识符。
3 clientSecret：客户端密钥。
4 clientAuthenticationMethod：用于客户端向提供方进行身份验证的方法。 支持的值包括 client_secret_basic、client_secret_post、private_key_jwt、client_secret_jwt 和 none （公共客户端）。
5 authorizationGrantType：OAuth 2.0 授权框架定义了四种授权许可（Authorization Grant）类型。 支持的值包括 authorization_code、client_credentials，以及扩展许可类型 urn:ietf:params:oauth:grant-type:jwt-bearer。
6 redirectUri：客户端注册的重定向 URI，授权服务器在最终用户完成身份验证并授权客户端访问后，将最终用户的用户代理重定向到该 URI。
7 scopes：客户端在授权请求流程中所请求的范围（scope），例如 openid、email 或 profile。
8 clientName：用于客户端的描述性名称。 该名称可能在某些场景中使用，例如在自动生成的登录页面中显示客户端的名称。
9 authorizationUri：授权服务器的授权端点 URI。
10 tokenUri：授权服务器的Tokens端点 URI。
11 jwkSetUri：用于从授权服务器检索JSON Web 密钥（JWK）集的 URI，该密钥集包含用于验证 ID Token 的JSON Web 签名（JWS）以及（可选地）UserInfo 响应的加密密钥。
12 issuerUri：返回 OpenID Connect 1.0 提供商或 OAuth 2.0 授权服务器的颁发者标识符 URI。
13 configurationMetadata：OpenID 提供者配置信息。 仅当配置了 Spring Boot 属性 spring.security.oauth2.client.provider.[providerId].issuerUri 时，此信息才可用。
14 (userInfoEndpoint)uri：用于访问已认证最终用户的声明（claims）和属性（attributes）的 UserInfo 端点 URI。
15 (userInfoEndpoint)authenticationMethod：向 UserInfo 端点发送访问Tokens时所使用的认证方法。 支持的值包括 header、form 和 query。
16 userNameAttributeName：在 UserInfo 响应中返回的属性名称，该属性引用最终用户的名称或标识符。
17 requireProofKey: If true或者clientAuthenticationMethod is none，则 PKCE 将被启用。默认值为true对于authorization_code授权类型和false适用于其他授权类型。

您可以通过发现 OpenID Connect 提供商的配置端点或授权服务器的元数据端点，来初始配置一个https://tools.ietf.org/html/rfc8414#section-3。spring-doc.cadn.net.cn

ClientRegistrations 提供了便捷方法，用于以如下方式配置 ClientRegistration：spring-doc.cadn.net.cn

ClientRegistration clientRegistration =
    ClientRegistrations.fromIssuerLocation("https://idp.example.com/issuer").build();
val clientRegistration = ClientRegistrations.fromIssuerLocation("https://idp.example.com/issuer").build()

上述代码依次查询 idp.example.com/issuer/.well-known/openid-configuration、idp.example.com/.well-known/openid-configuration/issuer 和 idp.example.com/.well-known/oauth-authorization-server/issuer，并在第一个返回 200 响应的地址处停止。spring-doc.cadn.net.cn

或者，您可以使用 ClientRegistrations.fromOidcIssuerLocation() 仅查询 OpenID Connect 提供商的配置端点。spring-doc.cadn.net.cn

客户端注册仓库

ClientRegistrationRepository 用作 OAuth 2.0 / OpenID Connect 1.0 ClientRegistration（客户端注册信息）的存储库。spring-doc.cadn.net.cn

客户端注册信息最终由关联的授权服务器存储和拥有。 该仓库提供了检索主客户端注册信息子集的能力，这些信息存储在授权服务器中。spring-doc.cadn.net.cn

Spring Boot 自动配置将 spring.security.oauth2.client.registration.[registrationId] 下的每个属性绑定到一个 ClientRegistration 实例，然后将每个 ClientRegistration 实例组合到一个 ClientRegistrationRepository 中。spring-doc.cadn.net.cn

ClientRegistrationRepository 的默认实现是 InMemoryClientRegistrationRepository。spring-doc.cadn.net.cn

自动配置还会将 ClientRegistrationRepository 注册为 @Bean 中的一个 ApplicationContext，以便在应用程序需要时可用于依赖注入。spring-doc.cadn.net.cn

以下列表展示了一个示例：spring-doc.cadn.net.cn

@Controller
public class OAuth2ClientController {

	@Autowired
	private ClientRegistrationRepository clientRegistrationRepository;

	@GetMapping("/")
	public String index() {
		ClientRegistration oktaRegistration =
			this.clientRegistrationRepository.findByRegistrationId("okta");

		...

		return "index";
	}
}
@Controller
class OAuth2ClientController {

    @Autowired
    private lateinit var clientRegistrationRepository: ClientRegistrationRepository

    @GetMapping("/")
    fun index(): String {
        val oktaRegistration =
                this.clientRegistrationRepository.findByRegistrationId("okta")

        //...

        return "index";
    }
}

OAuth2 授权客户端

OAuth2AuthorizedClient 是已授权客户端的一种表示形式。 当最终用户（资源所有者）已授予客户端访问其受保护资源的授权时，该客户端即被视为已授权。spring-doc.cadn.net.cn

OAuth2AuthorizedClient 用于将一个 OAuth2AccessToken（以及可选的 OAuth2RefreshToken）与一个 ClientRegistration（客户端）和资源所有者关联起来，该资源所有者是授予授权的 Principal 最终用户。spring-doc.cadn.net.cn

OAuth2AuthorizedClientRepository 和 OAuth2AuthorizedClientService

OAuth2AuthorizedClientRepository 负责在 Web 请求之间持久化 OAuth2AuthorizedClient（们），而 OAuth2AuthorizedClientService 的主要职责是在应用级别管理 OAuth2AuthorizedClient（们）。spring-doc.cadn.net.cn

从开发人员的角度来看，OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService 提供了查找与客户端关联的 OAuth2AccessToken 的能力，以便使用该Tokens发起受保护资源的请求。spring-doc.cadn.net.cn

以下列表展示了一个示例：spring-doc.cadn.net.cn

@Controller
public class OAuth2ClientController {

    @Autowired
    private OAuth2AuthorizedClientService authorizedClientService;

    @GetMapping("/")
    public String index(Authentication authentication) {
        OAuth2AuthorizedClient authorizedClient =
            this.authorizedClientService.loadAuthorizedClient("okta", authentication.getName());

        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        ...

        return "index";
    }
}
@Controller
class OAuth2ClientController {

    @Autowired
    private lateinit var authorizedClientService: OAuth2AuthorizedClientService

    @GetMapping("/")
    fun index(authentication: Authentication): String {
        val authorizedClient: OAuth2AuthorizedClient =
            this.authorizedClientService.loadAuthorizedClient("okta", authentication.getName());
        val accessToken = authorizedClient.accessToken

        ...

        return "index";
    }
}

Spring Boot 自动配置会在 OAuth2AuthorizedClientRepository 中注册一个 OAuth2AuthorizedClientService 或 @Bean 的 ApplicationContext。 然而，应用程序可以覆盖并注册自定义的 OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService @Bean。spring-doc.cadn.net.cn

OAuth2AuthorizedClientService 的默认实现是 InMemoryOAuth2AuthorizedClientService，它将 OAuth2AuthorizedClient 对象存储在内存中。spring-doc.cadn.net.cn

或者，您可以配置 JDBC 实现 JdbcOAuth2AuthorizedClientService，将 OAuth2AuthorizedClient 实例持久化到数据库中。spring-doc.cadn.net.cn

JdbcOAuth2AuthorizedClientService 依赖于OAuth 2.0 客户端模式中描述的表定义。spring-doc.cadn.net.cn

OAuth2AuthorizedClientManager 和 OAuth2AuthorizedClientProvider

OAuth2AuthorizedClientManager 负责对 OAuth2AuthorizedClient（们）进行整体管理。spring-doc.cadn.net.cn

主要职责包括：spring-doc.cadn.net.cn

  • 通过使用 OAuth2AuthorizedClientProvider 来授权（或重新授权）一个 OAuth 2.0 客户端。spring-doc.cadn.net.cn

  • 委托持久化 OAuth2AuthorizedClient，通常通过使用 OAuth2AuthorizedClientService 或 OAuth2AuthorizedClientRepository 来实现。spring-doc.cadn.net.cn

  • 当 OAuth 2.0 客户端成功完成授权（或重新授权）时，委托给 OAuth2AuthorizationSuccessHandler。spring-doc.cadn.net.cn

  • 当 OAuth 2.0 客户端授权（或重新授权）失败时，委托给 OAuth2AuthorizationFailureHandler 进行处理。spring-doc.cadn.net.cn

OAuth2AuthorizedClientProvider 实现了一种用于授权（或重新授权）OAuth 2.0 客户端的策略。 其实现通常对应一种授权许可类型，例如 authorization_code、client_credentials 等。spring-doc.cadn.net.cn

OAuth2AuthorizedClientManager 的默认实现是 DefaultOAuth2AuthorizedClientManager，它关联了一个 OAuth2AuthorizedClientProvider，该提供者可通过基于委托的组合方式支持多种授权许可类型。 您可以使用 OAuth2AuthorizedClientProviderBuilder 来配置并构建这种基于委托的组合。spring-doc.cadn.net.cn

以下代码展示了如何配置并构建一个 OAuth2AuthorizedClientProvider 组合对象，该对象支持 authorization_code、refresh_token 和 client_credentials 授权许可类型：spring-doc.cadn.net.cn

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
		ClientRegistrationRepository clientRegistrationRepository,
		OAuth2AuthorizedClientRepository authorizedClientRepository) {

	OAuth2AuthorizedClientProvider authorizedClientProvider =
			OAuth2AuthorizedClientProviderBuilder.builder()
					.authorizationCode()
					.refreshToken()
					.clientCredentials()
					.build();

	DefaultOAuth2AuthorizedClientManager authorizedClientManager =
			new DefaultOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientRepository);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	return authorizedClientManager;
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .authorizationCode()
            .refreshToken()
            .clientCredentials()
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

当授权尝试成功时，DefaultOAuth2AuthorizedClientManager 会委托给 OAuth2AuthorizationSuccessHandler，后者（默认情况下）通过 OAuth2AuthorizedClientRepository 保存 OAuth2AuthorizedClient。 在重新授权失败的情况下（例如刷新Tokens不再有效），之前保存的 OAuth2AuthorizedClient 会通过 RemoveAuthorizedClientOAuth2AuthorizationFailureHandler 从 OAuth2AuthorizedClientRepository 中移除。 您可以通过 setAuthorizationSuccessHandler(OAuth2AuthorizationSuccessHandler) 和 setAuthorizationFailureHandler(OAuth2AuthorizationFailureHandler) 自定义默认行为。spring-doc.cadn.net.cn

DefaultOAuth2AuthorizedClientManager 还关联了一个类型为 contextAttributesMapper 的 Function<OAuth2AuthorizeRequest, Map<String, Object>>，它负责将 OAuth2AuthorizeRequest 中的属性映射到一个 Map 中，该 OAuth2AuthorizationContext 的属性将与 OAuth2AuthorizedClientProvider 关联。 当你需要向 7 提供所需的（受支持的）属性时，这会非常有用。spring-doc.cadn.net.cn

以下代码展示了 contextAttributesMapper 的一个示例：spring-doc.cadn.net.cn

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
		ClientRegistrationRepository clientRegistrationRepository,
		OAuth2AuthorizedClientRepository authorizedClientRepository) {

	OAuth2AuthorizedClientProvider authorizedClientProvider =
			OAuth2AuthorizedClientProviderBuilder.builder()
					.authorizationCode()
					.refreshToken()
					.build();

	DefaultOAuth2AuthorizedClientManager authorizedClientManager =
			new DefaultOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientRepository);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	// Assuming the attributes are supplied as `HttpServletRequest` parameters,
	// map the `HttpServletRequest` parameters to `OAuth2AuthorizationContext.getAttributes()`
	authorizedClientManager.setContextAttributesMapper(contextAttributesMapper());

	return authorizedClientManager;
}

private Function<OAuth2AuthorizeRequest, Map<String, Object>> contextAttributesMapper() {
	return authorizeRequest -> {
		Map<String, Object> contextAttributes = Collections.emptyMap();
		HttpServletRequest servletRequest = authorizeRequest.getAttribute(HttpServletRequest.class.getName());
		String param1 = servletRequest.getParameter("param1");
		String param2 = servletRequest.getParameter("param2");
		if (StringUtils.hasText(param1) && StringUtils.hasText(param2)) {
			contextAttributes = new HashMap<>();
			contextAttributes.put("param1", param1);
			contextAttributes.put("param2", param2);
		}
		return contextAttributes;
	};
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .authorizationCode()
            .refreshToken()
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

	// Assuming the attributes are supplied as `HttpServletRequest` parameters,
	// map the `HttpServletRequest` parameters to `OAuth2AuthorizationContext.getAttributes()`
    authorizedClientManager.setContextAttributesMapper(contextAttributesMapper())
    return authorizedClientManager
}

private fun contextAttributesMapper(): Function<OAuth2AuthorizeRequest, MutableMap<String, Any>> {
    return Function { authorizeRequest ->
        var contextAttributes: MutableMap<String, Any> = mutableMapOf()
        val servletRequest: HttpServletRequest = authorizeRequest.getAttribute(HttpServletRequest::class.java.name)
        val param1: String = servletRequest.getParameter("param1")
        val param2: String = servletRequest.getParameter("param2")
        if (StringUtils.hasText(param1) && StringUtils.hasText(param2)) {
            contextAttributes = hashMapOf()
            contextAttributes["param1"] = param1
            contextAttributes["param2"] = param2
        }
        contextAttributes
    }
}

DefaultOAuth2AuthorizedClientManager 设计用于 HttpServletRequest 上下文内部。 当在 HttpServletRequest 上下文之外运行时，请改用 AuthorizedClientServiceOAuth2AuthorizedClientManager。spring-doc.cadn.net.cn

服务应用程序是使用 AuthorizedClientServiceOAuth2AuthorizedClientManager 的一个常见场景。 服务应用程序通常在后台运行，无需任何用户交互，并且通常以系统级账户而非用户账户运行。 配置了 client_credentials 授权类型的 OAuth 2.0 客户端可被视为一种服务应用程序。spring-doc.cadn.net.cn

以下代码展示了如何配置一个支持 AuthorizedClientServiceOAuth2AuthorizedClientManager 授权类型的 client_credentials 的示例：spring-doc.cadn.net.cn

@Bean
public OAuth2AuthorizedClientManager authorizedClientManager(
		ClientRegistrationRepository clientRegistrationRepository,
		OAuth2AuthorizedClientService authorizedClientService) {

	OAuth2AuthorizedClientProvider authorizedClientProvider =
			OAuth2AuthorizedClientProviderBuilder.builder()
					.clientCredentials()
					.build();

	AuthorizedClientServiceOAuth2AuthorizedClientManager authorizedClientManager =
			new AuthorizedClientServiceOAuth2AuthorizedClientManager(
					clientRegistrationRepository, authorizedClientService);
	authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

	return authorizedClientManager;
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientService: OAuth2AuthorizedClientService): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .clientCredentials()
            .build()
    val authorizedClientManager = AuthorizedClientServiceOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientService)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}