此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Security 6.4.1！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

一个ClientRegistrationobject 包含客户端 ID、客户端密钥、授权授权类型、重定向 URI、范围、授权 URI、令牌 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)

		}
	}
}
1 registrationId：唯一标识ClientRegistration.
2 clientId：客户端标识符。
3 clientSecret：客户端密钥。
4 clientAuthenticationMethod：用于向 Provider 验证 Client 的方法。 支持的值为 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，授权服务器重定向最终用户的用户代理 更改为最终用户对客户端进行身份验证和授权访问后。
7 scopes：客户端在授权请求流程中请求的范围，例如 openid、email 或 profile。
8 clientName：用于客户端的描述性名称。 该名称可能在某些情况下使用，例如在自动生成的登录页面中显示客户端的名称时。
9 authorizationUri：授权服务器的授权端点 URI。
10 tokenUri：授权服务器的令牌端点 URI。
11 jwkSetUri：用于从授权服务器检索 JSON Web 密钥 （JWK） 集的 URI， 其中包含用于验证 ID 令牌的 JSON Web 签名 （JWS） 和（可选）UserInfo 响应的加密密钥。
12 issuerUri：返回 OpenID Connect 1.0 提供者或 OAuth 2.0 授权服务器的颁发者标识符 URI。
13 configurationMetadata：OpenID Provider 配置信息。 仅当 Spring Boot 2.x 属性spring.security.oauth2.client.provider.[providerId].issuerUri已配置。
14 (userInfoEndpoint)uri：用于访问经过身份验证的最终用户的声明和属性的 UserInfo 端点 URI。
15 (userInfoEndpoint)authenticationMethod：将 Access Token 发送到 UserInfo Endpoint 时使用的身份验证方法。 支持的值为 header、form 和 query。
16 userNameAttributeName：UserInfo 响应中返回的属性名称，该属性引用最终用户的 Name 或 Identifier。

您可以最初配置ClientRegistration通过使用 OpenID Connect Provider 的配置端点或 Authorization Server 的元数据端点的发现。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 Provider 的配置终端节点。spring-doc.cadn.net.cn

ClientRegistrationRepository

这ClientRegistrationRepository用作 OAuth 2.0 / OpenID Connect 1.0 的存储库ClientRegistration（s） 的spring-doc.cadn.net.cn

客户端注册信息最终由关联的 Authorization Server 存储和拥有。 此存储库提供了检索主客户端注册信息子集的功能，该信息与 Authorization Server 一起存储。spring-doc.cadn.net.cn

Spring Boot 2.x 自动配置绑定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";
    }
}

OAuth2AuthorizedClient

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

OAuth2AuthorizedClient用于将OAuth2AccessToken（并且可选OAuth2RefreshToken） 转换为ClientRegistration（客户端）和资源所有者，后者是Principal授予授权的最终用户。spring-doc.cadn.net.cn

OAuth2AuthorizedClientRepository 和 OAuth2AuthorizedClientService

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

从开发人员的角度来看，OAuth2AuthorizedClientRepository或OAuth2AuthorizedClientService提供查找OAuth2AccessToken与客户端关联，以便可以使用它来启动受保护的资源请求。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 2.x 自动配置会注册一个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（s） 的spring-doc.cadn.net.cn

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

  • 授权（或重新授权）OAuth 2.0 客户端，使用OAuth2AuthorizedClientProvider.spring-doc.cadn.net.cn

  • 委托OAuth2AuthorizedClient，通常通过使用OAuth2AuthorizedClientService或OAuth2AuthorizedClientRepository.spring-doc.cadn.net.cn

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

  • 委托给OAuth2AuthorizationFailureHandler当 OAuth 2.0 客户端无法授权（或重新授权）时。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和password授权授权类型：spring-doc.cadn.net.cn

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

授权尝试成功后，DefaultOAuth2AuthorizedClientManagerdelegates 到OAuth2AuthorizationSuccessHandler，它（默认情况下）将OAuth2AuthorizedClient通过OAuth2AuthorizedClientRepository. 如果重新授权失败（例如，刷新令牌不再有效），则之前保存的OAuth2AuthorizedClient已从OAuth2AuthorizedClientRepository通过RemoveAuthorizedClientOAuth2AuthorizationFailureHandler. 您可以通过以下方式自定义默认行为setAuthorizationSuccessHandler(OAuth2AuthorizationSuccessHandler)和setAuthorizationFailureHandler(OAuth2AuthorizationFailureHandler).spring-doc.cadn.net.cn

这DefaultOAuth2AuthorizedClientManager还与contextAttributesMapper的类型Function<OAuth2AuthorizeRequest, Map<String, Object>>，它负责从OAuth2AuthorizeRequest更改为Map要关联的OAuth2AuthorizationContext. 当您需要提供OAuth2AuthorizedClientProvider具有必需（支持）属性，例如。这PasswordOAuth2AuthorizedClientProvider需要资源所有者的username和password可用于OAuth2AuthorizationContext.getAttributes().spring-doc.cadn.net.cn

以下代码显示了contextAttributesMapper:spring-doc.cadn.net.cn

@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. 在HttpServletRequestcontext， 使用AuthorizedClientServiceOAuth2AuthorizedClientManager相反。spring-doc.cadn.net.cn

服务应用程序是何时使用AuthorizedClientServiceOAuth2AuthorizedClientManager. 服务应用程序通常在后台运行，无需任何用户交互，并且通常在系统级账户（而不是用户账户）下运行。 配置了client_credentials授权类型可以被视为一种服务应用程序类型。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
}