Core Interfaces and Classes

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

ClientRegistration

OAuth2AccessToken 是向 OAuth 2.0 或 OpenID Connect 1.0 提供程序注册的客户端的表示形式。

OAuth2AuthorizedClient 对象包含诸如客户端 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: The client identifier.
3 clientSecret: The client secret.
4 clientAuthenticationMethod：用于用提供程序验证客户端的方法。支持的值为 client_secret_basic、client_secret_post、private_key_jwt、client_secret_jwt 和 none (public clients)。
5 authorizationGrantType：OAuth 2.0 授权框架定义了四种 Authorization Grant 类型。支持的值为 authorization_code、client_credentials、password，以及扩展授权类型 urn:ietf:params:oauth:grant-type:jwt-bearer。
6 redirectUri：客户端的已注册重定向 URI，Authorization Server 在最终用户经过身份验证和授权客户端访问权限后会将最终用户的用户代理重定向到该 URI。
7 scopes：在授权请求流期间客户端请求的范围，例如 openid、email 或 profile。
8 clientName：用于客户端的说明性名称。在某些情况下可以使用该名称，例如在自动生成的登录页面中显示客户端的名称时。
9 authorizationUri：授权服务器的授权端点 URI。
10 tokenUri：授权服务器的令牌端点 URI。
11 jwkSetUri：用于从授权服务器中检索 JSON Web Key (JWK) 集的 URI，其中包含用于验证 ID 令牌的 JSON Web Signature (JWS) 和（可选）UserInfo 响应的加密密钥。
12 issuerUri：返回 OpenID Connect 1.0 提供程序或 OAuth 2.0 授权服务器的发行人标识符 URI。
13 configurationMetadata： OpenID Provider Configuration Information. 仅当 Spring Boot 2.x 属性 spring.security.oauth2.client.provider.[providerId].issuerUri 已配置时才可获取此信息。
14 (userInfoEndpoint)uri：用于访问已验证最终用户的主张和属性的 UserInfo 端点 URI。
15 (userInfoEndpoint)authenticationMethod：向 UserInfo 端点发送访问令牌时所用的验证方法。支持的值有 header、form 和 query。
16 userNameAttributeName：引用最终用户姓名或标识符的 UserInfo 响应中返回的属性名称。

你可以通过发现 OpenID Connect 提供程序的 ClientRegistration 或授权服务器的 ClientRegistration 初始配置 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()

上述代码按顺序查询 ClientRegistrations、ClientRegistration 和 https://idp.example.com/issuer/.well-known/openid-configuration，在第一个返回 200 响应时停止。

作为备用办法，您可以使用 ClientRegistrations.fromOidcIssuerLocation() 仅查询 OpenID Connect 提供程序的配置端点。

ClientRegistrationRepository

ClientRegistrationRepository 作为 OAuth 2.0/OpenID Connect 1.0 ClientRegistration 的储存库。

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

Spring Boot 2.x 自动配置将 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 and 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 2.x 自动配置在 ApplicationContext 中注册了一个 OAuth2AuthorizedClientRepository 或一个 OAuth2AuthorizedClientService @Bean。但是，应用程序可以覆盖并注册一个自定义 OAuth2AuthorizedClientRepository 或 OAuth2AuthorizedClientService @Bean。

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

或者，您可以配置 JDBC 实现 JdbcOAuth2AuthorizedClientService 以将 OAuth2AuthorizedClient 实例持续存在于数据库中。

JdbcOAuth2AuthorizedClientService 取决于 OAuth 2.0 Client Schema 中描述的表定义。

OAuth2AuthorizedClientManager and OAuth2AuthorizedClientProvider

OAuth2AuthorizedClientManager 负责 OAuth2AuthorizedClient 的整体管理。

主要职责包括：

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

  • 通常通过使用 OAuth2AuthorizedClientService 或 OAuth2AuthorizedClientRepository 委派 OAuth2AuthorizedClient 的持久性。

  • 当 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 上下文中 within 使用的。当在 HttpServletRequest 上下文的 outside 中操作时，改用 AuthorizedClientServiceOAuth2AuthorizedClientManager 。

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

以下代码显示了如何配置支持 client_credentials 授权类型的 AuthorizedClientServiceOAuth2AuthorizedClientManager 的示例：

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