Advanced Configuration

OAuth 2.0 授权框架将 Protocol Endpoints 定义如下: 授权过程使用两个授权服务器端点(HTTP 资源):

  • 授权终端:供客户端通过用户代理重定向从资源所有者获得授权。

  • 令牌端点:Client 用于将授权授权交换为访问令牌,通常使用 Client 认证。

以及一个客户端端点:

  • 重定向终端:供授权服务器通过资源所有者用户代理向客户端返回包含授权凭据的响应。

OpenID Connect 核心 1.0 规范将 UserInfo Endpoint 定义如下: UserInfo 端点是一个 OAuth 2.0 受保护资源,返回有关经过身份验证的最终用户的信息。为了获得有关最终用户请求的信息,客户端使用通过 OpenID Connect Authentication 获得的访问令牌,向 UserInfo 端点发出请求。这些信息通常由一个 JSON 对象表示,该对象包含一系列用于信息的名称-值对。 ServerHttpSecurity.oauth2Login() 提供了许多配置选项,用于定制 OAuth 2.0 登录。 以下代码显示了 oauth2Login() DSL 可用的完整配置选项:

OAuth2 Login Configuration Options
  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
		http
			.oauth2Login(oauth2 -> oauth2
				.authenticationConverter(this.authenticationConverter())
				.authenticationMatcher(this.authenticationMatcher())
				.authenticationManager(this.authenticationManager())
				.authenticationSuccessHandler(this.authenticationSuccessHandler())
				.authenticationFailureHandler(this.authenticationFailureHandler())
				.clientRegistrationRepository(this.clientRegistrationRepository())
				.authorizedClientRepository(this.authorizedClientRepository())
				.authorizedClientService(this.authorizedClientService())
				.authorizationRequestResolver(this.authorizationRequestResolver())
				.authorizationRequestRepository(this.authorizationRequestRepository())
				.securityContextRepository(this.securityContextRepository())
			);

		return http.build();
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login {
                authenticationConverter = authenticationConverter()
                authenticationMatcher = authenticationMatcher()
                authenticationManager = authenticationManager()
                authenticationSuccessHandler = authenticationSuccessHandler()
                authenticationFailureHandler = authenticationFailureHandler()
                clientRegistrationRepository = clientRegistrationRepository()
                authorizedClientRepository = authorizedClientRepository()
                authorizedClientService = authorizedClientService()
                authorizationRequestResolver = authorizationRequestResolver()
                authorizationRequestRepository = authorizationRequestRepository()
                securityContextRepository = securityContextRepository()
            }
        }

        return http.build()
    }
}

以下各节将详细介绍每个可用的配置选项:

OAuth 2.0 Login Page

默认情况下,OAuth 2.0 登录页是由 LoginPageGeneratingWebFilter 自动生成的。默认登录页显示每个配置的 OAuth 客户端及其 ClientRegistration.clientName 作为一个链接,该链接能够启动授权请求(或 OAuth 2.0 登录)。

为了使 LoginPageGeneratingWebFilter 显示已配置的 OAuth 客户端的链接,已注册的 ReactiveClientRegistrationRepository 也需要实现 Iterable<ClientRegistration>。请参阅 InMemoryReactiveClientRegistrationRepository 以备参考。

每个 OAuth 客户端的链接目标默认为以下内容:

"/oauth2/authorization/{registrationId}"

以下行为示例:

<a href="/oauth2/authorization/google">Google</a>

要覆盖默认登录页,请配置 exceptionHandling().authenticationEntryPoint() 和(可选)oauth2Login().authorizationRequestResolver()

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

OAuth2 Login Page Configuration
  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			.exceptionHandling(exceptionHandling -> exceptionHandling
				.authenticationEntryPoint(new RedirectServerAuthenticationEntryPoint("/login/oauth2"))
			)
			.oauth2Login(oauth2 -> oauth2
				.authorizationRequestResolver(this.authorizationRequestResolver())
			);

		return http.build();
	}

	private ServerOAuth2AuthorizationRequestResolver authorizationRequestResolver() {
		ServerWebExchangeMatcher authorizationRequestMatcher =
				new PathPatternParserServerWebExchangeMatcher(
						"/login/oauth2/authorization/{registrationId}");

		return new DefaultServerOAuth2AuthorizationRequestResolver(
				this.clientRegistrationRepository(), authorizationRequestMatcher);
	}

	...
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            exceptionHandling {
                authenticationEntryPoint = RedirectServerAuthenticationEntryPoint("/login/oauth2")
            }
            oauth2Login {
                authorizationRequestResolver = authorizationRequestResolver()
            }
        }

        return http.build()
    }

    private fun authorizationRequestResolver(): ServerOAuth2AuthorizationRequestResolver {
        val authorizationRequestMatcher: ServerWebExchangeMatcher = PathPatternParserServerWebExchangeMatcher(
            "/login/oauth2/authorization/{registrationId}"
        )

        return DefaultServerOAuth2AuthorizationRequestResolver(
            clientRegistrationRepository(), authorizationRequestMatcher
        )
    }

    ...
}

您需要提供一个 @Controller 及其 @RequestMapping("/login/oauth2"),能够呈现自定义登录页面。

如前所述,配置 oauth2Login().authorizationRequestResolver() 是可选的。但是,如果您选择定制它,请确保到每个 OAuth 客户端的链接与通过 ServerWebExchangeMatcher 提供的模式相匹配。 以下行为示例:

<a href="/login/oauth2/authorization/google">Google</a>

Redirection Endpoint

重定向端点由授权服务器用于通过资源所有者用户代理将授权响应(包含授权凭据)返回给客户端。

OAuth 2.0 登录利用授权代码授予。因此,授权凭证就是授权代码。

默认授权响应重定向端点是 /login/oauth2/code/{registrationId}

如果您想要定制授权响应重定向端点,请按照以下示例中的说明进行配置:

Redirection Endpoint Configuration
  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			.oauth2Login(oauth2 -> oauth2
				.authenticationMatcher(new PathPatternParserServerWebExchangeMatcher("/login/oauth2/callback/{registrationId}"))
			);

		return http.build();
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login {
                authenticationMatcher = PathPatternParserServerWebExchangeMatcher("/login/oauth2/callback/{registrationId}")
            }
        }

        return http.build()
    }
}

您还需要确保 ClientRegistration.redirectUri 与自定义授权响应重定向端点匹配。 下面的清单显示了一个示例:

Java
return CommonOAuth2Provider.GOOGLE.getBuilder("google")
	.clientId("google-client-id")
	.clientSecret("google-client-secret")
	.redirectUri("{baseUrl}/login/oauth2/callback/{registrationId}")
	.build();
Kotlin
return CommonOAuth2Provider.GOOGLE.getBuilder("google")
    .clientId("google-client-id")
    .clientSecret("google-client-secret")
    .redirectUri("{baseUrl}/login/oauth2/callback/{registrationId}")
    .build()

UserInfo Endpoint

UserInfo 终结点包括多个配置选项,如下小节所述:

Mapping User Authorities

用户在 OAuth 2.0 提供商处成功认证后,OAuth2User.getAuthorities() (或 OidcUser.getAuthorities()) 包含从 OAuth2UserRequest.getAccessToken().getScopes() 中填充的授权列表,并在其之前加上 SCOPE_。这些授权可能被映射到 GrantedAuthority 实例的新集合,它会在完成认证时提供给 OAuth2AuthenticationToken

OAuth2AuthenticationToken.getAuthorities() 用于授权请求,例如 hasRole('USER')hasRole('ADMIN') 中的请求。

在映射用户权限时有几个选项可供选择:

Using a GrantedAuthoritiesMapper

GrantedAuthoritiesMapper 具有被授予的权限列表,其中包含 OAuth2UserAuthority 类型和权限字符串 OAUTH2_USER(或 OidcUserAuthority 和权限字符串 OIDC_USER)的特殊权限。

注册一个 GrantedAuthoritiesMapper @Bean 以使其自动应用到配置中,如以下示例所示:

Granted Authorities Mapper Configuration
  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			...
			.oauth2Login(withDefaults());

		return http.build();
	}

	@Bean
	public GrantedAuthoritiesMapper userAuthoritiesMapper() {
		return (authorities) -> {
			Set<GrantedAuthority> mappedAuthorities = new HashSet<>();

			authorities.forEach(authority -> {
				if (OidcUserAuthority.class.isInstance(authority)) {
					OidcUserAuthority oidcUserAuthority = (OidcUserAuthority)authority;

					OidcIdToken idToken = oidcUserAuthority.getIdToken();
					OidcUserInfo userInfo = oidcUserAuthority.getUserInfo();

					// Map the claims found in idToken and/or userInfo
					// to one or more GrantedAuthority's and add it to mappedAuthorities

				} else if (OAuth2UserAuthority.class.isInstance(authority)) {
					OAuth2UserAuthority oauth2UserAuthority = (OAuth2UserAuthority)authority;

					Map<String, Object> userAttributes = oauth2UserAuthority.getAttributes();

					// Map the attributes found in userAttributes
					// to one or more GrantedAuthority's and add it to mappedAuthorities

				}
			});

			return mappedAuthorities;
		};
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login { }
        }

        return http.build()
    }

    @Bean
    fun userAuthoritiesMapper(): GrantedAuthoritiesMapper = GrantedAuthoritiesMapper { authorities: Collection<GrantedAuthority> ->
        val mappedAuthorities = emptySet<GrantedAuthority>()

        authorities.forEach { authority ->
            if (authority is OidcUserAuthority) {
                val idToken = authority.idToken
                val userInfo = authority.userInfo
                // Map the claims found in idToken and/or userInfo
                // to one or more GrantedAuthority's and add it to mappedAuthorities
            } else if (authority is OAuth2UserAuthority) {
                val userAttributes = authority.attributes
                // Map the attributes found in userAttributes
                // to one or more GrantedAuthority's and add it to mappedAuthorities
            }
        }

        mappedAuthorities
    }
}

Delegation-based strategy with ReactiveOAuth2UserService

与使用 GrantedAuthoritiesMapper 相比,此策略更加高级,不过,它也更加灵活,因为它允许您访问 OAuth2UserRequestOAuth2User(使用 OAuth 2.0 UserService 时)或 OidcUserRequestOidcUser(使用 OpenID Connect 1.0 UserService 时)。

OAuth2UserRequest(和 OidcUserRequest)使您能访问关联的 OAuth2AccessToken,在 delegator 需要在为用户映射自定义授权之前从受保护资源中获取授权信息的情况下,此访问非常有用。

以下示例展示了如何使用 OpenID Connect 1.0 UserService 实现和配置基于委派的策略:

ReactiveOAuth2UserService Configuration
  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			...
			.oauth2Login(withDefaults());

		return http.build();
	}

	@Bean
	public ReactiveOAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
		final OidcReactiveOAuth2UserService delegate = new OidcReactiveOAuth2UserService();

		return (userRequest) -> {
			// Delegate to the default implementation for loading a user
			return delegate.loadUser(userRequest)
					.flatMap((oidcUser) -> {
						OAuth2AccessToken accessToken = userRequest.getAccessToken();
						Set<GrantedAuthority> mappedAuthorities = new HashSet<>();

						// TODO
						// 1) Fetch the authority information from the protected resource using accessToken
						// 2) Map the authority information to one or more GrantedAuthority's and add it to mappedAuthorities

						// 3) Create a copy of oidcUser but use the mappedAuthorities instead
						ProviderDetails providerDetails = userRequest.getClientRegistration().getProviderDetails();
						String userNameAttributeName = providerDetails.getUserInfoEndpoint().getUserNameAttributeName();
						if (StringUtils.hasText(userNameAttributeName)) {
							oidcUser = new DefaultOidcUser(mappedAuthorities, oidcUser.getIdToken(), oidcUser.getUserInfo(), userNameAttributeName);
						} else {
							oidcUser = new DefaultOidcUser(mappedAuthorities, oidcUser.getIdToken(), oidcUser.getUserInfo());
						}

						return Mono.just(oidcUser);
					});
		};
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login { }
        }

        return http.build()
    }

    @Bean
    fun oidcUserService(): ReactiveOAuth2UserService<OidcUserRequest, OidcUser> {
        val delegate = OidcReactiveOAuth2UserService()

        return ReactiveOAuth2UserService { userRequest ->
            // Delegate to the default implementation for loading a user
            delegate.loadUser(userRequest)
                .flatMap { oidcUser ->
                    val accessToken = userRequest.accessToken
                    val mappedAuthorities = mutableSetOf<GrantedAuthority>()

                    // TODO
                    // 1) Fetch the authority information from the protected resource using accessToken
                    // 2) Map the authority information to one or more GrantedAuthority's and add it to mappedAuthorities
                    // 3) Create a copy of oidcUser but use the mappedAuthorities instead
                    val providerDetails = userRequest.getClientRegistration().getProviderDetails()
                    val userNameAttributeName = providerDetails.getUserInfoEndpoint().getUserNameAttributeName()
                    val mappedOidcUser = if (StringUtils.hasText(userNameAttributeName)) {
                        DefaultOidcUser(mappedAuthorities, oidcUser.idToken, oidcUser.userInfo, userNameAttributeName)
                    } else {
                        DefaultOidcUser(mappedAuthorities, oidcUser.idToken, oidcUser.userInfo)
                    }

                    Mono.just(mappedOidcUser)
                }
        }
    }
}

OAuth 2.0 UserService

DefaultReactiveOAuth2UserServiceReactiveOAuth2UserService 的实现,它支持标准 OAuth 2.0 提供商。

ReactiveOAuth2UserService 从 UserInfo 端点(使用在授权流程期间授予客户端的访问令牌)获取最终用户(资源拥有者)用户属性并返回 AuthenticatedPrincipal,格式为 OAuth2User

DefaultReactiveOAuth2UserService 在 UserInfo 端点请求用户属性时使用 WebClient

如果您需要定制 UserInfo 请求的预处理和/或 UserInfo 响应的后处理,您需要用自定义配置的 WebClientDefaultReactiveOAuth2UserService.setWebClient() 提供。

无论您定制 DefaultReactiveOAuth2UserService 还是提供 ReactiveOAuth2UserService 的自定义实现,您都需要按照以下示例中的说明进行配置:

  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			...
			.oauth2Login(withDefaults());

		return http.build();
	}

	@Bean
	public ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService() {
		...
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login { }
        }

        return http.build()
    }

    @Bean
    fun oauth2UserService(): ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> {
        // ...
    }
}

OpenID Connect 1.0 UserService

OidcReactiveOAuth2UserServiceReactiveOAuth2UserService 的实现,它支持 OpenID Connect 1.0 提供商。

OidcReactiveOAuth2UserService 在 UserInfo 端点请求用户属性时利用 DefaultReactiveOAuth2UserService

如果您需要定制 UserInfo 请求的预处理和/或 UserInfo 响应的后处理,您需要用自定义配置的 ReactiveOAuth2UserServiceOidcReactiveOAuth2UserService.setOauth2UserService() 提供。

无论您定制 OidcReactiveOAuth2UserService 还是为 OpenID Connect 1.0 提供商提供 ReactiveOAuth2UserService 的自定义实现,您都需要按照以下示例中的说明进行配置:

  • Java

  • Kotlin

@Configuration
@EnableWebFluxSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
		http
			...
			.oauth2Login(withDefaults());

		return http.build();
	}

	@Bean
	public ReactiveOAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
		...
	}
}
@Configuration
@EnableWebFluxSecurity
class OAuth2LoginSecurityConfig {

    @Bean
    fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
        http {
            oauth2Login { }
        }

        return http.build()
    }

    @Bean
    fun oidcUserService(): ReactiveOAuth2UserService<OidcUserRequest, OidcUser> {
        // ...
    }
}

ID Token Signature Verification

OpenID Connect 1.0 认证引入了 ID Token ,该 ID Token 是一个安全令牌,其中包含由授权服务器在客户端使用时对最终用户的认证索赔。

ID 令牌表示为 JSON Web Token(JWT),并且必须使用 JSON Web Signature(JWS)进行签名。

ReactiveOidcIdTokenDecoderFactory 提供了 ReactiveJwtDecoder,用于 OidcIdToken 签名验证。默认算法为 RS256,但在客户端注册期间分配时,可能不同。对于这些情况,可以配置解析器以返回为特定客户端分配的预期 JWS 算法。

JWS 算法解析器是 Function,它接受 ClientRegistration,并为客户端返回预期 JwsAlgorithm,比如 SignatureAlgorithm.RS256MacAlgorithm.HS256

以下代码展示了如何配置 OidcIdTokenDecoderFactory @Bean,使其对所有 ClientRegistration 默认使用 MacAlgorithm.HS256

  • Java

  • Kotlin

@Bean
public ReactiveJwtDecoderFactory<ClientRegistration> idTokenDecoderFactory() {
	ReactiveOidcIdTokenDecoderFactory idTokenDecoderFactory = new ReactiveOidcIdTokenDecoderFactory();
	idTokenDecoderFactory.setJwsAlgorithmResolver(clientRegistration -> MacAlgorithm.HS256);
	return idTokenDecoderFactory;
}
@Bean
fun idTokenDecoderFactory(): ReactiveJwtDecoderFactory<ClientRegistration> {
    val idTokenDecoderFactory = ReactiveOidcIdTokenDecoderFactory()
    idTokenDecoderFactory.setJwsAlgorithmResolver { MacAlgorithm.HS256 }
    return idTokenDecoderFactory
}

对于诸如 HS256HS384HS512 的基于 MAC 的算法,与 client-id 对应的 client-secret 用于签名验证的对称密钥。

如果为 OpenID Connect 1.0 身份验证配置了多个 ClientRegistration,则 JWS 算法解析器可能会评估提供的 ClientRegistration 来确定要返回哪个算法。

然后,可以继续配置 logout