跳到主要内容
版本：7.0.2

高级配置

DeepSeek V3 中英对照 Advanced Configuration

HttpSecurity.oauth2Login() 为自定义 OAuth 2.0 登录提供了多种配置选项。主要配置选项按其对应的协议端点进行分组。

例如，oauth2Login().authorizationEndpoint() 用于配置授权端点，而 oauth2Login().tokenEndpoint() 则用于配置令牌端点。

以下代码展示了一个示例：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .authorizationEndpoint((authorization) -> authorization
			            ...
			    )
			    .redirectionEndpoint((redirection) -> redirection
			            ...
			    )
			    .tokenEndpoint((token) -> token
			            ...
			    )
			    .userInfoEndpoint((userInfo) -> userInfo
			            ...
			    )
			);
		return http.build();
	}
}

oauth2Login() DSL 的主要目标是严格遵循规范中定义的命名规则。

OAuth 2.0 授权框架将 协议端点 定义如下：

授权过程使用两个授权服务器端点（HTTP 资源）：

  • 授权端点：客户端通过用户代理重定向，从资源所有者处获取授权。

  • 令牌端点：客户端用于将授权许可交换为访问令牌，通常伴随客户端身份验证。

授权过程也使用一个客户端端点：

  • 重定向端点：授权服务器通过资源所有者用户代理，向客户端返回包含授权凭证的响应时使用。

OpenID Connect Core 1.0 规范将 UserInfo 端点 定义如下：

用户信息端点（UserInfo Endpoint）是一个 OAuth 2.0 受保护资源，用于返回经过身份验证的最终用户的相关声明。客户端通过使用通过 OpenID Connect 身份验证获得的访问令牌，向用户信息端点发起请求，以获取关于最终用户的所需声明。这些声明通常由一个包含声明名称-值对集合的 JSON 对象表示。

以下代码展示了 oauth2Login() DSL 可用的完整配置选项：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .clientRegistrationRepository(this.clientRegistrationRepository())
			    .authorizedClientRepository(this.authorizedClientRepository())
			    .authorizedClientService(this.authorizedClientService())
			    .loginPage("/login")
			    .authorizationEndpoint((authorization) -> authorization
			        .baseUri(this.authorizationRequestBaseUri())
			        .authorizationRequestRepository(this.authorizationRequestRepository())
			        .authorizationRequestResolver(this.authorizationRequestResolver())
			    )
			    .redirectionEndpoint((redirection) -> redirection
			        .baseUri(this.authorizationResponseBaseUri())
			    )
			    .tokenEndpoint((token) -> token
			        .accessTokenResponseClient(this.accessTokenResponseClient())
			    )
			    .userInfoEndpoint((userInfo) -> userInfo
			        .userAuthoritiesMapper(this.userAuthoritiesMapper())
			        .userService(this.oauth2UserService())
			        .oidcUserService(this.oidcUserService())
			    )
			);
		return http.build();
	}
}

除了 oauth2Login() DSL 之外，也支持 XML 配置。

以下代码展示了 security 命名空间 中可用的完整配置选项：

<http>
	<oauth2-login client-registration-repository-ref="clientRegistrationRepository"
				  authorized-client-repository-ref="authorizedClientRepository"
				  authorized-client-service-ref="authorizedClientService"
				  authorization-request-repository-ref="authorizationRequestRepository"
				  authorization-request-resolver-ref="authorizationRequestResolver"
				  access-token-response-client-ref="accessTokenResponseClient"
				  user-authorities-mapper-ref="userAuthoritiesMapper"
				  user-service-ref="oauth2UserService"
				  oidc-user-service-ref="oidcUserService"
				  login-processing-url="/login/oauth2/code/*"
				  login-page="/login"
				  authentication-success-handler-ref="authenticationSuccessHandler"
				  authentication-failure-handler-ref="authenticationFailureHandler"
				  jwt-decoder-factory-ref="jwtDecoderFactory"/>
</http>

以下章节将详细说明各项可用配置选项：

OAuth 2.0 登录页面​

默认情况下，OAuth 2.0 登录页面由 DefaultLoginPageGeneratingFilter 自动生成。该默认登录页面会显示每个已配置的 OAuth 客户端，并以 ClientRegistration.clientName 作为链接，该链接能够发起授权请求（或 OAuth 2.0 登录）。

备注

为了让 DefaultLoginPageGeneratingFilter 显示已配置的 OAuth 客户端的链接，已注册的 ClientRegistrationRepository 也需要实现 Iterable<ClientRegistration> 接口。请参考 InMemoryClientRegistrationRepository。

每个 OAuth 客户端的链接目标默认指向以下地址：

OAuth2AuthorizationRequestRedirectFilter.DEFAULT_AUTHORIZATION_REQUEST_BASE_URI + "/{registrationId}"

以下行展示了一个示例：

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

要覆盖默认的登录页面，请配置 oauth2Login().loginPage() 以及（可选）oauth2Login().authorizationEndpoint().baseUri()。

以下清单展示了一个示例：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .loginPage("/login/oauth2")
			    ...
			    .authorizationEndpoint((authorization) -> authorization
			        .baseUri("/login/oauth2/authorization")
			        ...
			    )
			);
		return http.build();
	}
}

:::重要
你需要提供一个带有 @RequestMapping("/login/oauth2") 的 @Controller，该控制器能够渲染自定义的登录页面。
:::

提示

如前所述，配置 oauth2Login().authorizationEndpoint().baseUri() 是可选的。但是，如果你选择自定义它，请确保每个 OAuth 客户端的链接与 authorizationEndpoint().baseUri() 相匹配。

下面这行代码展示了一个示例：

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

重定向端点​

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

提示

OAuth 2.0 登录利用了授权码许可类型。因此，授权凭证就是授权码。

默认的授权响应 baseUri（重定向端点）为 **/login/oauth2/code/*，该值定义于 OAuth2LoginAuthenticationFilter.DEFAULT_FILTER_PROCESSES_URI 中。

如果您希望自定义授权响应的 baseUri，请按以下方式配置：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .redirectionEndpoint((redirection) -> redirection
			        .baseUri("/login/oauth2/callback/*")
			        ...
			    )
			);
		return http.build();
	}
}
important

你还需要确保 ClientRegistration.redirectUri 与自定义的授权响应 baseUri 相匹配。

以下示例展示了具体做法：

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

用户信息端点​

UserInfo端点包含多个配置选项，具体说明如下：

映射用户权限​

用户通过 OAuth 2.0 提供者成功认证后，OAuth2User.getAuthorities()（或 OidcUser.getAuthorities()）会包含一个已授予权限的列表，该列表从 OAuth2UserRequest.getAccessToken().getScopes() 中填充，并添加了 SCOPE_ 前缀。这些已授予的权限可以映射为一组新的 GrantedAuthority 实例，并在完成认证时提供给 OAuth2AuthenticationToken。

提示

OAuth2AuthenticationToken.getAuthorities() 用于授权请求，例如在 hasRole('USER') 或 hasRole('ADMIN') 中。

在映射用户权限时，有以下几种选项可供选择：

使用 GrantedAuthoritiesMapper​

GrantedAuthoritiesMapper 接收一个包含特殊权限类型 OAuth2UserAuthority 及其权限字符串 OAUTH2_USER（或 OidcUserAuthority 及其权限字符串 OIDC_USER）的已授权权限列表。

提供 GrantedAuthoritiesMapper 的实现并进行配置，如下所示：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .userInfoEndpoint((userInfo) -> userInfo
			        .userAuthoritiesMapper(this.userAuthoritiesMapper())
			        ...
			    )
			);
		return http.build();
	}

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

或者，你也可以注册一个 GrantedAuthoritiesMapper @Bean，使其自动应用于配置，如下所示：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
		    .oauth2Login(withDefaults());
		return http.build();
	}

	@Bean
	public GrantedAuthoritiesMapper userAuthoritiesMapper() {
		...
	}
}
提示

认证完成后，它还会包含授予的 FACTOR_AUTHORIZATION_CODE 权限。

基于委托策略的 OAuth2UserService​

与使用 GrantedAuthoritiesMapper 相比，此策略更为先进。同时，它也更具灵活性，因为它让你能够访问 OAuth2UserRequest 和 OAuth2User（当使用 OAuth 2.0 UserService 时）或 OidcUserRequest 和 OidcUser（当使用 OpenID Connect 1.0 UserService 时）。

OAuth2UserRequest（以及OidcUserRequest）为您提供了对关联的OAuth2AccessToken的访问权限，这在委托方需要从受保护资源获取权限信息后才能为用户映射自定义权限的情况下非常有用。

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

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .userInfoEndpoint((userInfo) -> userInfo
			        .oidcUserService(this.oidcUserService())
			        ...
			    )
			);
		return http.build();
	}

	private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
		final OidcUserService delegate = new OidcUserService();

		return (userRequest) -> {
			// Delegate to the default implementation for loading a user
			OidcUser oidcUser = delegate.loadUser(userRequest);

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

OAuth 2.0 用户服务​

DefaultOAuth2UserService 是 OAuth2UserService 的一个实现，它支持标准的 OAuth 2.0 提供商。

备注

OAuth2UserService 从用户信息端点（通过使用在授权流程中授予客户端的访问令牌）获取终端用户（资源所有者）的用户属性，并以 OAuth2User 的形式返回一个 AuthenticatedPrincipal。

DefaultOAuth2UserService 在向用户信息端点请求用户属性时，会使用一个 RestOperations 实例。

如果你需要自定义用户信息请求的预处理，可以通过 DefaultOAuth2UserService.setRequestEntityConverter() 方法提供一个自定义的 Converter<OAuth2UserRequest, RequestEntity<?>>。默认实现 OAuth2UserRequestEntityConverter 会构建一个用户信息请求的 RequestEntity 表示，该表示默认将 OAuth2AccessToken 设置在 Authorization 请求头中。

另一方面，如果您需要自定义 UserInfo 响应的后处理逻辑，则需要通过 DefaultOAuth2UserService.setRestOperations() 方法提供一个经过自定义配置的 RestOperations 实例。默认的 RestOperations 配置如下：

RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(new OAuth2ErrorResponseErrorHandler());

OAuth2ErrorResponseErrorHandler 是一个 ResponseErrorHandler，能够处理 OAuth 2.0 错误（400 Bad Request）。它使用 OAuth2ErrorHttpMessageConverter 将 OAuth 2.0 错误参数转换为 OAuth2Error。

无论你是自定义 DefaultOAuth2UserService 还是提供自己的 OAuth2UserService 实现，都需要按如下方式进行配置：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
			    .userInfoEndpoint((userInfo) -> userInfo
			        .userService(this.oauth2UserService())
			        ...
			    )
			);
		return http.build();
	}

	private OAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService() {
		...
	}
}

OpenID Connect 1.0 用户服务​

OidcUserService 是一个支持 OpenID Connect 1.0 提供商的 OAuth2UserService 实现。

OidcUserService 在向用户信息端点请求用户属性时，会利用 DefaultOAuth2UserService。

若需自定义用户信息请求的预处理或用户信息响应的后处理，需通过 OidcUserService.setOauth2UserService() 方法提供一个自定义配置的 DefaultOAuth2UserService。

无论你是自定义 OidcUserService，还是为 OpenID Connect 1.0 提供者提供自己的 OAuth2UserService 实现，都需要按如下方式进行配置：

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

	@Bean
	public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
		http
			.oauth2Login((oauth2) -> oauth2
				.userInfoEndpoint((userInfo) -> userInfo
				    .oidcUserService(this.oidcUserService())
				    ...
			    )
			);
		return http.build();
	}

	private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
		...
	}
}

ID 令牌签名验证​

OpenID Connect 1.0 认证引入了 ID Token，这是一种安全令牌，当客户端使用时，它包含有关授权服务器对终端用户进行认证的声明。

ID Token 以 JSON Web Token (JWT) 的形式表示，并且必须使用 JSON Web Signature (JWS) 进行签名。

OidcIdTokenDecoderFactory 提供用于 OidcIdToken 签名验证的 JwtDecoder。默认算法为 RS256，但在客户端注册期间分配时可能有所不同。对于这些情况，您可以配置一个解析器来返回为特定客户端分配的预期 JWS 算法。

JWS算法解析器是一个Function，它接收一个ClientRegistration并返回该客户端预期的JwsAlgorithm，例如SignatureAlgorithm.RS256或MacAlgorithm.HS256。

以下代码展示了如何配置 OidcIdTokenDecoderFactory @Bean，使其为所有 ClientRegistration 实例默认使用 MacAlgorithm.HS256 算法：

@Bean
public JwtDecoderFactory<ClientRegistration> idTokenDecoderFactory() {
	OidcIdTokenDecoderFactory idTokenDecoderFactory = new OidcIdTokenDecoderFactory();
	idTokenDecoderFactory.setJwsAlgorithmResolver((clientRegistration) -> clientRegistration.HS256);
	return idTokenDecoderFactory;
}
备注

对于基于 MAC 的算法（例如 HS256、HS384 或 HS512），与 client-id 对应的 client-secret 被用作验证签名的对称密钥。

提示

如果为 OpenID Connect 1.0 认证配置了多个 ClientRegistration，JWS 算法解析器可能会评估所提供的 ClientRegistration 以确定返回哪种算法。

接下来，你可以继续配置登出功能。