跳到主要内容
版本：6.4.3

高级配置

QWen Max 中英对照 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 端点是一个受 OAuth 2.0 保护的资源，它返回关于已认证终端用户的信息。为了获取关于终端用户的请求信息，客户端使用通过 OpenID Connect 认证获得的访问令牌向 UserInfo 端点发起请求。这些声明通常由一个 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();
    }
}
important

你需要提供一个带有 @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 端点​

UserInfo Endpoint 包含若干配置选项，如下所述：

映射用户权限​

用户成功通过 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() {
        ...
    }
}

基于委托的策略与 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 UserService​

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

备注

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

DefaultOAuth2UserService 在请求用户信息端点的用户属性时使用 RestOperations 实例。

如果你需要自定义 UserInfo 请求的预处理，可以为 DefaultOAuth2UserService.setRequestEntityConverter() 提供一个自定义的 Converter<OAuth2UserRequest, RequestEntity<?>>。默认实现 OAuth2UserRequestEntityConverter 会构建一个 RequestEntity 表示的 UserInfo 请求，并默认在 Authorization 头中设置 OAuth2AccessToken。

在另一方面，如果你需要自定义对 UserInfo 响应的后处理，你需要提供一个自定义配置的 RestOperations 给 DefaultOAuth2UserService.setRestOperations()。默认的 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 UserService​

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

OidcUserService 在请求 UserInfo 端点的用户属性时利用了 DefaultOAuth2UserService。

如果你需要自定义 UserInfo 请求的预处理或 UserInfo 响应的后处理，你需要为 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 Token 签名验证​

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 OidcIdTokenDecoderFactory idTokenDecoderFactory() {
    return new OidcIdTokenDecoderFactory() {
        @Override
        public JwtDecoder createDecoder(ClientRegistration clientRegistration) {
            if (clientRegistration.getProviderDetails().getConfigurationMetadata().containsKey("jwk_set_uri")) {
                // Use NimbusJwtDecoder for JWKs
                return new NimbusJwtDecoder(JwkSetUriJwtDecoderBuilder.create(clientRegistration).build());
            } else {
                // Default to HS256 for symmetric key
                return new NimbusJwtDecoder(new ImmutableSecret<>(clientRegistration.getClientSecret().getBytes()));
            }
        }
    };
}
@Bean
public JwtDecoderFactory<ClientRegistration> idTokenDecoderFactory() {
    OidcIdTokenDecoderFactory idTokenDecoderFactory = new OidcIdTokenDecoderFactory();
    idTokenDecoderFactory.setJwsAlgorithmResolver(clientRegistration -> MacAlgorithm.HS256);
    return idTokenDecoderFactory;
}
备注

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

提示

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

然后，您可以继续配置logout