# 核心接口/类

# 客户登记

ClientRegistration是在OAuth2.0或OpenID Connect1.0提供程序中注册的客户端的表示。

客户机注册包含信息,例如客户机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:用于与提供程序验证客户端的方法。
支持的值是**客户端_Secret_BASIC **,**客户端_Secret_post **,**Private_Key_JWT **,客户端_Secret_JWT (公众客户) (opens new window)
5 authorizationGrantType:OAuth2.0授权框架定义了四个授权授予 (opens new window)类型。
支持的值是authorization_codeclient_credentialspassword,以及,扩展授权类型urn:ietf:params:oauth:grant-type:jwt-bearer
6 redirectUri:客户端注册的重定向URI,在最终用户对客户端进行了身份验证和授权访问之后,授权服务器将最终用户的用户代理
重定向到该URI。
7 scopes:客户端在授权请求流期间请求的范围,例如OpenID、电子邮件或配置文件。
8 clientName:用于客户机的描述性名称。
该名称可用于某些场景,例如在自动生成的登录页面中显示客户机的名称时。
9 authorizationUri:授权服务器的授权端点URI。
10 tokenUri:授权服务器的令牌端点URI。
11 jwkSetUri:用于从授权服务器检索JSON Web Key (opens new window)集的URI,
,其中包含用于验证ID令牌的JSON Web签名 (opens new window)的加密密钥,以及可选的userinfo响应。
12 issuerUri:返回OpenID Connect1.0提供程序或OAuth2.0授权服务器的发行者标识符URI。
13 configurationMetadata:OpenID提供者配置信息 (opens new window).
只有在配置了 Spring boot2.x属性spring.security.oauth2.client.provider.[providerId].issuerUri时,该信息才可用。
14 (userInfoEndpoint)uri:用于访问经过身份验证的最终用户的声明/属性的userinfo端点URI。
15 (userInfoEndpoint)authenticationMethod:向UserInfo端点发送访问令牌时使用的身份验证方法。
支持的值是页眉形式查询
16 userNameAttributeName:在引用最终用户的名称或标识符的UserInfo响应中返回的属性的名称。

可以使用发现OpenID Connect提供者的配置端点 (opens new window)或授权服务器的元数据端点 (opens new window)来初始配置ClientRegistration

ClientRegistrations以这种方式为配置ClientRegistration提供了方便的方法,如下例所示:

Java

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

Kotlin

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

上面的代码将在系列[https://idp.example.com/issuer/.well-known/openid-configuration](https://idp.example.com/issuer/.well-known/openid-configuration)中查询,然后[https://idp.example.com/.well-known/openid-configuration/issuer](https://idp.example.com/.well-known/openid-configuration/issuer),最后是[https://idp.example.com/.well-known/oauth-authorization-server/issuer](https://idp.example.com/.well-known/oauth-authorization-server/issuer),在第一次停止时返回200响应。

作为一种替代方法,你可以使用ClientRegistrations.fromOidcIssuerLocation()仅查询OpenID Connect提供者的配置端点。

# ClientRegistrationRepository

ClientRegistrationRepository充当OAuth2.0/OpenID Connect1.0ClientRegistration(s)的存储库。

客户端注册信息最终由关联的授权服务器存储和拥有。
此存储库提供检索主客户端注册信息的子集的能力,该子集与授权服务器一起存储。

Spring Boot2.x Auto-Configuration将spring.security.oauth2.client.registration.*[registrationId]*下的每个属性绑定到ClientRegistration的一个实例,然后在ClientRegistration中组合每个ClientRegistration实例。

ClientRegistrationRepository的默认实现是InMemoryClientRegistrationRepository

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

下面的清单展示了一个示例:

Java

@Controller
public class OAuth2ClientController {

	@Autowired
	private ClientRegistrationRepository clientRegistrationRepository;

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

		...

		return "index";
	}
}

Kotlin

@Controller
class OAuth2ClientController {

    @Autowired
    private lateinit var clientRegistrationRepository: ClientRegistrationRepository

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

        //...

        return "index";
    }
}

# OAuth2授权客户端

OAuth2AuthorizedClient是授权客户的表示。当最终用户(资源所有者)已向客户端授予访问其受保护资源的授权时,客户端被视为已被授权。

OAuth2AuthorizedClient的目的是将OAuth2AccessToken(和可选OAuth2RefreshToken)关联到ClientRegistration(客户端)和资源所有者,后者是授予授权的Principal最终用户。

# OAuth2authorizedClientPository/OAuth2authorizedClientService

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

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

下面的清单展示了一个示例:

Java

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

Kotlin

@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 Boot2.x自动配置在ApplicationContext中注册一个OAuth2AuthorizedClientRepository和/或OAuth2AuthorizedClientService``@Bean
但是,应用程序可以选择重写并注册一个自定义的OAuth2AuthorizedClientRepositoryOAuth2AuthorizedClientService

OAuth2AuthorizedClientService的默认实现是InMemoryOAuth2AuthorizedClientService,它在内存中存储OAuth2AuthorizedClient

或者,可以将JDBC实现JdbcOAuth2AuthorizedClientService配置为在数据库中持久化OAuth2AuthorizedClient

JdbcOAuth2AuthorizedClientService取决于OAuth2.0客户端模式中描述的表定义。

# OAuth2AuthorizedClientManager/OAuth2AuthorizedClientProvider

OAuth2AuthorizedClientManager负责OAuth2AuthorizedClient(s)的全面管理。

主要职责包括:

  • 使用OAuth2AuthorizedClientProvider对OAuth2.0客户端进行授权(或重新授权)。

  • 委派OAuth2AuthorizedClient的持久性,通常使用OAuth2AuthorizedClientServiceOAuth2AuthorizedClientRepository

  • 当一个OAuth2.0客户端已被成功授权(或重新授权)时,将其委托给OAuth2AuthorizationSuccessHandler

  • 当OAuth2.0客户端未能授权(或重新授权)时,将其委托给OAuth2AuthorizationFailureHandler

OAuth2AuthorizedClientProvider实现了对OAuth2.0客户端进行授权(或重新授权)的策略。实现通常将实现一种授权授予类型,例如。authorization_codeclient_credentials等。

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

下面的代码展示了如何配置和构建OAuth2AuthorizedClientProvider组合的示例,该组合为authorization_coderefresh_tokenclient_credentialspassword授权授予类型提供支持:

Java

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

Kotlin

@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,该(默认情况下)将通过OAuth2AuthorizedClient保存OAuth2AuthorizedClient。在重新授权失败的情况下,例如,刷新令牌不再有效,先前保存的OAuth2AuthorizedClient将通过RemoveAuthorizedClientOAuth2AuthorizationFailureHandlerOAuth2AuthorizedClientRepository中删除。默认行为可以通过setAuthorizationSuccessHandler(OAuth2AuthorizationSuccessHandler)setAuthorizationFailureHandler(OAuth2AuthorizationFailureHandler)进行定制。

DefaultOAuth2AuthorizedClientManager还与类型Function<OAuth2AuthorizeRequest, Map<String, Object>>contextAttributesMapper相关联,它负责将属性从OAuth2AuthorizeRequest映射到要与OAuth2AuthorizationContext相关联的属性的Map。当你需要提供带有Required(Supported)属性的OAuth2AuthorizedClientProvider时,这可能是有用的,例如,PasswordOAuth2AuthorizedClientProvider要求资源所有者的usernamepasswordOAuth2AuthorizationContext.getAttributes()中可用。

下面的代码显示了contextAttributesMapper的示例:

Java

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

Kotlin

@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_credentialsgrant类型的OAuth2.0客户机可以被视为服务应用程序的一种类型。

下面的代码展示了如何配置AuthorizedClientServiceOAuth2AuthorizedClientManager的示例,该示例为client_credentialsgrant类型提供支持:

Java

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

Kotlin

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

OAuth2客户端OAuth2授权授予