Spring Boot集成Okta时组角色转换及Principal属性异常问题

一、将Okta Groups转换为带ROLE_前缀的Spring Security角色 #

当前你的Groups以普通权限形式存在（如App-User），而Spring Security的hasRole()方法默认要求权限带ROLE_前缀，因此需要自定义权限映射逻辑：

1. 创建自定义GrantedAuthoritiesMapper

import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.core.oidc.user.OidcUserAuthority;
import java.util.Collection;
import java.util.stream.Collectors;

public class OktaGroupsToRolesMapper implements GrantedAuthoritiesMapper {
    @Override
    public Collection<? extends GrantedAuthority> mapAuthorities(Collection<? extends GrantedAuthority> authorities) {
        return authorities.stream()
                .map(authority -> {
                    if (authority instanceof OidcUserAuthority oidcAuth) {
                        // 处理groups claim，添加ROLE_前缀
                        return oidcAuth.getAttributes().get("groups") instanceof Collection<?> groups
                                ? groups.stream()
                                        .map(group -> new SimpleGrantedAuthority("ROLE_" + group))
                                        .collect(Collectors.toList())
                                : null;
                    }
                    // 保留原有权限（如SCOPE_*、OIDC_USER）
                    return authority;
                })
                .flatMap(Collection::stream)
                .collect(Collectors.toSet());
    }
}

2. 在Security配置中应用该映射器

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserService;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .authorizeHttpRequests(auth -> auth
                        .anyRequest().authenticated()
                )
                .oauth2Login(oauth2 -> oauth2
                        .userInfoEndpoint(userInfo -> userInfo
                                .oidcUserService(oidcUserService())
                        )
                );
        return http.build();
    }

    @Bean
    public OidcUserService oidcUserService() {
        OidcUserService userService = new OidcUserService();
        userService.setAuthoritiesMapper(new OktaGroupsToRolesMapper());
        return userService;
    }
}

配置完成后，principal.authorities会包含ROLE_App-User，此时<div sec:authorize="hasRole('App-User')">You have the role</div>即可正常生效。

二、修复Principal的name属性与用户信息获取问题 #

1. 检查Okta授权服务器的Claim配置 #

登录Okta管理后台，进入Security > API > 授权服务器，选择你的授权服务器：

• 进入Claims标签页，确保已添加以下claims并设置正确：
  • email：包含用户邮箱，设置为Always返回
  • given_name：用户名字，设置为Always返回
  • family_name：用户姓氏，设置为Always返回
  • name：可选，若需要自定义用户名，可设置为user.firstName + " " + user.lastName或直接用user.email

2. 自定义OidcUser实现（可选，更灵活） #

如果需要直接通过principal.firstName等属性访问，可自定义UserDetails对象：

import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.oidc.OidcUserInfo;
import org.springframework.security.oauth2.core.oidc.user.DefaultOidcUser;
import java.util.Collection;

public class CustomOktaUser extends DefaultOidcUser {
    private final String firstName;
    private final String lastName;
    private final String email;

    public CustomOktaUser(Collection<? extends GrantedAuthority> authorities, OidcIdToken idToken, OidcUserInfo userInfo) {
        super(authorities, idToken, userInfo);
        this.firstName = userInfo.getGivenName();
        this.lastName = userInfo.getFamilyName();
        this.email = userInfo.getEmail();
    }

    public String getFirstName() {
        return firstName;
    }

    public String getLastName() {
        return lastName;
    }

    @Override
    public String getName() {
        // 这里可以自定义返回用户名，比如邮箱或姓名
        return this.email;
    }
}

然后修改OidcUserService返回自定义用户：

@Bean
public OidcUserService oidcUserService() {
    OidcUserService userService = new OidcUserService();
    userService.setAuthoritiesMapper(new OktaGroupsToRolesMapper());
    
    // 替换为自定义用户
    userService.setOidcUserConverter(userResponse -> {
        OidcUserInfo userInfo = userResponse.getUserInfo();
        OidcIdToken idToken = userResponse.getIdToken();
        Collection<? extends GrantedAuthority> authorities = userService.getAuthorities(userResponse);
        return new CustomOktaUser(authorities, idToken, userInfo);
    });
    
    return userService;
}

配置完成后：

• <div sec:authentication="principal.name"></div>会返回你自定义的用户名（如邮箱）
• <div sec:authentication="principal.firstName"></div>可正常获取用户名字

内容的提问来源于stack exchange，提问作者Steve Maring