核心接口和类

本节描述了 Spring Security 提供的 OAuth2 核心接口和类。

ClientRegistration

ClientRegistration 代表向 OAuth 2.0 或 OpenID Connect 1.0 提供程序注册的客户端。

ClientRegistration 对象保存信息，例如客户端 ID、客户端密钥、授权授权类型、重定向 URI、范围、授权 URI、令牌 URI 和其他详细信息。

ClientRegistration 及其属性定义如下：

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)

		}
	}
}
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_code、client_credentials、password，以及扩展授权类型 urn:ietf:params:oauth:grant-type:jwt-bearer。
6 redirectUri：客户端注册的重定向 URI，在最终用户完成身份验证并授权访问客户端后，*授权服务器* 将最终用户的用户代理重定向到该 URI。
7 scopes：客户端在授权请求流程中请求的范围，例如 openid、email 或 profile。
8 clientName：客户端的描述性名称。该名称可能用于某些场景，例如在自动生成的登录页面中显示客户端的名称。
9 authorizationUri：授权服务器的授权端点 URI。
10 tokenUri：授权服务器的令牌端点 URI。
11 jwkSetUri：用于从授权服务器检索 JSON Web 密钥 (JWK) 集的 URI，该集合包含用于验证 ID 令牌的 JSON Web 签名 (JWS) （以及可选的用户信息响应）的加密密钥。
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：用于访问已验证最终用户的声明和属性的用户信息端点 URI。
15 (userInfoEndpoint)authenticationMethod：向用户信息端点发送访问令牌时使用的身份验证方法。支持的值为 **header**、**form** 和 **query**。
16 userNameAttributeName：用户信息响应中返回的属性名称，用于引用最终用户的姓名或标识符。

您可以最初使用 OpenID Connect 提供程序的 配置端点 或授权服务器的 元数据端点 来配置 ClientRegistration。

ClientRegistrations 提供了以下方便的方法来以这种方式配置 ClientRegistration

  • Java

  • Kotlin

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 响应时停止。

或者，您可以使用 ClientRegistrations.fromOidcIssuerLocation() 只查询 OpenID Connect 提供程序的配置端点。

ClientRegistrationRepository

ClientRegistrationRepository 充当 OAuth 2.0 / OpenID Connect 1.0 ClientRegistration 的存储库。

客户端注册信息最终由关联的授权服务器存储和拥有。此存储库提供检索存储在授权服务器中的主要客户端注册信息子集的功能。

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

ClientRegistrationRepository 的默认实现是 InMemoryClientRegistrationRepository。

自动配置还在 ApplicationContext 中将 ClientRegistrationRepository 注册为 @Bean，以便应用程序需要时可以使用依赖注入。

以下列表显示了一个示例

  • Java

  • Kotlin

@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";
    }
}

OAuth2AuthorizedClient

OAuth2AuthorizedClient 是授权客户端的表示。当最终用户（资源所有者）已授予客户端访问其受保护资源的授权时，客户端被认为是已授权的。

OAuth2AuthorizedClient 用于将 OAuth2AccessToken（和可选的 OAuth2RefreshToken）与 ClientRegistration（客户端）和资源所有者关联，资源所有者是授予授权的 Principal 最终用户。

OAuth2AuthorizedClientRepository 和 OAuth2AuthorizedClientService

OAuth2AuthorizedClientRepository 负责在 Web 请求之间持久化 OAuth2AuthorizedClient，而 OAuth2AuthorizedClientService 的主要作用是在应用程序级别管理 OAuth2AuthorizedClient。

从开发人员的角度来看，OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService 提供了查找与客户端关联的 OAuth2AccessToken 的功能，以便可以使用它来启动受保护的资源请求。

以下列表显示了一个示例

  • Java

  • Kotlin

@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 自动配置在 ApplicationContext 中注册 OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService @Bean。但是，应用程序可以覆盖并注册自定义的 OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService @Bean。

OAuth2AuthorizedClientService 的默认实现是 InMemoryOAuth2AuthorizedClientService，它将 OAuth2AuthorizedClient 对象存储在内存中。

或者，您可以配置 JDBC 实现 JdbcOAuth2AuthorizedClientService 以将 OAuth2AuthorizedClient 实例持久化到数据库中。

JdbcOAuth2AuthorizedClientService 依赖于 OAuth 2.0 客户端架构 中描述的表定义。

OAuth2AuthorizedClientManager 和 OAuth2AuthorizedClientProvider

OAuth2AuthorizedClientManager 负责 OAuth2AuthorizedClient 的整体管理。

主要职责包括：

  • 使用 OAuth2AuthorizedClientProvider 授权（或重新授权）OAuth 2.0 客户端。

  • 委托 OAuth2AuthorizedClient 的持久化，通常使用 OAuth2AuthorizedClientService 或 OAuth2AuthorizedClientRepository。

  • 当 OAuth 2.0 客户端成功授权（或重新授权）时，委托给 OAuth2AuthorizationSuccessHandler。

  • 当 OAuth 2.0 客户端授权（或重新授权）失败时，委托给 OAuth2AuthorizationFailureHandler。

OAuth2AuthorizedClientProvider 实现授权（或重新授权）OAuth 2.0 客户端的策略。实现通常实现授权授予类型，例如 authorization_code、client_credentials 等。

OAuth2AuthorizedClientManager 的默认实现是 DefaultOAuth2AuthorizedClientManager，它与可能支持使用基于委托的组合的多个授权授予类型的 OAuth2AuthorizedClientProvider 关联。您可以使用 OAuth2AuthorizedClientProviderBuilder 来配置和构建基于委托的组合。

以下代码显示了如何配置和构建一个 OAuth2AuthorizedClientProvider 组合，该组合支持 authorization_code、refresh_token、client_credentials 和 password 授权授予类型。

  • Java

  • Kotlin

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

	OAuth2AuthorizedClientProvider authorizedClientProvider =
			OAuth2AuthorizedClientProviderBuilder.builder()
					.authorizationCode()
					.refreshToken()
					.clientCredentials()
					.password()
					.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()
            .password()
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
    return authorizedClientManager
}

当授权尝试成功时，DefaultOAuth2AuthorizedClientManager 将委托给 OAuth2AuthorizationSuccessHandler，该处理程序（默认情况下）通过 OAuth2AuthorizedClientRepository 保存 OAuth2AuthorizedClient。如果重新授权失败（例如，刷新令牌不再有效），则先前保存的 OAuth2AuthorizedClient 将通过 RemoveAuthorizedClientOAuth2AuthorizationFailureHandler 从 OAuth2AuthorizedClientRepository 中删除。您可以通过 setAuthorizationSuccessHandler(OAuth2AuthorizationSuccessHandler) 和 setAuthorizationFailureHandler(OAuth2AuthorizationFailureHandler) 自定义默认行为。

DefaultOAuth2AuthorizedClientManager 还与类型为 Function<OAuth2AuthorizeRequest, Map<String, Object>> 的 contextAttributesMapper 关联，它负责将属性从 OAuth2AuthorizeRequest 映射到要与 OAuth2AuthorizationContext 关联的属性的 Map。当您需要向 OAuth2AuthorizedClientProvider 提供必需的（支持的）属性时，这很有用，例如，PasswordOAuth2AuthorizedClientProvider 需要资源所有者的 username 和 password 在 OAuth2AuthorizationContext.getAttributes() 中可用。

以下代码显示了 contextAttributesMapper 的示例

  • Java

  • Kotlin

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

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

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

	// Assuming the `username` and `password` 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 username = servletRequest.getParameter(OAuth2ParameterNames.USERNAME);
		String password = servletRequest.getParameter(OAuth2ParameterNames.PASSWORD);
		if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
			contextAttributes = new HashMap<>();

			// `PasswordOAuth2AuthorizedClientProvider` requires both attributes
			contextAttributes.put(OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME, username);
			contextAttributes.put(OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME, password);
		}
		return contextAttributes;
	};
}
@Bean
fun authorizedClientManager(
        clientRegistrationRepository: ClientRegistrationRepository,
        authorizedClientRepository: OAuth2AuthorizedClientRepository): OAuth2AuthorizedClientManager {
    val authorizedClientProvider = OAuth2AuthorizedClientProviderBuilder.builder()
            .password()
            .refreshToken()
            .build()
    val authorizedClientManager = DefaultOAuth2AuthorizedClientManager(
            clientRegistrationRepository, authorizedClientRepository)
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)

    // Assuming the `username` and `password` 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 username: String = servletRequest.getParameter(OAuth2ParameterNames.USERNAME)
        val password: String = servletRequest.getParameter(OAuth2ParameterNames.PASSWORD)
        if (StringUtils.hasText(username) && StringUtils.hasText(password)) {
            contextAttributes = hashMapOf()

            // `PasswordOAuth2AuthorizedClientProvider` requires both attributes
            contextAttributes[OAuth2AuthorizationContext.USERNAME_ATTRIBUTE_NAME] = username
            contextAttributes[OAuth2AuthorizationContext.PASSWORD_ATTRIBUTE_NAME] = password
        }
        contextAttributes
    }
}

DefaultOAuth2AuthorizedClientManager 旨在在 HttpServletRequest 的上下文中使用。在 HttpServletRequest 上下文之外运行时，请改用 AuthorizedClientServiceOAuth2AuthorizedClientManager。

服务应用程序是使用 AuthorizedClientServiceOAuth2AuthorizedClientManager 的常见用例。服务应用程序通常在后台运行，没有任何用户交互，并且通常在系统级帐户而不是用户帐户下运行。配置了 client_credentials 授予类型的 OAuth 2.0 客户端可以被认为是一种服务应用程序。

以下代码显示了如何配置一个 AuthorizedClientServiceOAuth2AuthorizedClientManager 来支持 client_credentials 授予类型

  • Java

  • Kotlin

@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
}