Keycloak + Spring Security 6 통합 — Resource Server와 OAuth2 Client 실전

dependencies {
    // API 서버라면
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
    // 로그인 주체 웹 앱이라면
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
}

# Resource Server
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://kc.example.com/realms/myrealm

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          # iss 클레임 검증 기준 (토큰에 박힌 외부 도메인)
          issuer-uri: https://kc.example.com/realms/myrealm
          # 실제 키 조회는 내부 네트워크로
          jwk-set-uri: http://keycloak.internal:8080/realms/myrealm/protocol/openid-connect/certs

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: web-app
            client-secret: WEB_APP_SECRET
            authorization-grant-type: authorization_code
            scope: openid, profile, email
        provider:
          keycloak:
            issuer-uri: https://kc.example.com/realms/myrealm

@Configuration
public class JwtDecoderConfig {

    @Bean
    JwtDecoder jwtDecoder(OAuth2ResourceServerProperties props) {
        String issuer = props.getJwt().getIssuerUri();
        NimbusJwtDecoder decoder = JwtDecoders.fromIssuerLocation(issuer);

        OAuth2TokenValidator<Jwt> issuerValidator =
                JwtValidators.createDefaultWithIssuer(issuer);
        OAuth2TokenValidator<Jwt> audienceValidator = new JwtClaimValidator<List<String>>(
                JwtClaimNames.AUD,
                aud -> aud != null && aud.contains("order-api"));

        decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
                issuerValidator, audienceValidator));
        return decoder;
    }
}

{
  "realm_access": {
    "roles": ["platform-admin", "offline_access"]
  },
  "resource_access": {
    "order-api": {
      "roles": ["order-viewer", "order-editor"]
    }
  },
  "scope": "openid profile email"
}

public class KeycloakJwtAuthenticationConverter
        implements Converter<Jwt, AbstractAuthenticationToken> {

    private static final String CLIENT_ID = "order-api";

    @Override
    public AbstractAuthenticationToken convert(Jwt jwt) {
        Collection<GrantedAuthority> authorities = Stream.concat(
                realmRoles(jwt), clientRoles(jwt, CLIENT_ID))
            .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
            .collect(Collectors.toSet());

        String principalName = jwt.getClaimAsString("preferred_username");
        return new JwtAuthenticationToken(jwt, authorities, principalName);
    }

    private Stream<String> realmRoles(Jwt jwt) {
        Map<String, Object> realmAccess = jwt.getClaimAsMap("realm_access");
        if (realmAccess == null) {
            return Stream.empty();
        }
        Object roles = realmAccess.get("roles");
        return roles instanceof Collection<?> c
                ? c.stream().map(Object::toString) : Stream.empty();
    }

    @SuppressWarnings("unchecked")
    private Stream<String> clientRoles(Jwt jwt, String clientId) {
        Map<String, Object> resourceAccess = jwt.getClaimAsMap("resource_access");
        if (resourceAccess == null) {
            return Stream.empty();
        }
        Object client = resourceAccess.get(clientId);
        if (!(client instanceof Map)) {
            return Stream.empty();
        }
        Object roles = ((Map<String, Object>) client).get("roles");
        return roles instanceof Collection<?> c
                ? c.stream().map(Object::toString) : Stream.empty();
    }
}

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class ResourceServerConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("platform-admin")
                .anyRequest().authenticated())
            .oauth2ResourceServer(rs -> rs.jwt(jwt ->
                jwt.jwtAuthenticationConverter(new KeycloakJwtAuthenticationConverter())));
        return http.build();
    }
}

@Service
public class OrderService {

    @PreAuthorize("hasRole('order-viewer')")
    public List<OrderSummary> list(String dept) { ... }

    @PreAuthorize("hasRole('order-editor') and #order.dept == authentication.token.claims['dept']")
    public Order create(Order order) { ... }

    @PostAuthorize("returnObject.ownerId == authentication.name")
    public Order findOne(Long id) { ... }
}

@Configuration
@EnableWebSecurity
public class WebAppSecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http,
            ClientRegistrationRepository registrations) throws Exception {

        OidcClientInitiatedLogoutSuccessHandler logoutHandler =
                new OidcClientInitiatedLogoutSuccessHandler(registrations);
        logoutHandler.setPostLogoutRedirectUri("{baseUrl}/logged-out");

        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/logged-out").permitAll()
                .anyRequest().authenticated())
            .oauth2Login(Customizer.withDefaults())
            .logout(logout -> logout.logoutSuccessHandler(logoutHandler));
        return http.build();
    }
}

http.oidcLogout(logout -> logout.backChannel(Customizer.withDefaults()));

@Configuration
public class MultiTenantSecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 허용된 issuer 목록 기반 — 신뢰 목록 방식
        JwtIssuerAuthenticationManagerResolver resolver =
                JwtIssuerAuthenticationManagerResolver.fromTrustedIssuers(
                        "https://kc.example.com/realms/tenant-a",
                        "https://kc.example.com/realms/tenant-b");

        http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .oauth2ResourceServer(rs -> rs.authenticationManagerResolver(resolver));
        return http.build();
    }
}

@Configuration
@EnableWebFluxSecurity
public class ReactiveSecurityConfig {

    @Bean
    SecurityWebFilterChain filterChain(ServerHttpSecurity http) {
        ReactiveJwtAuthenticationConverterAdapter converter =
                new ReactiveJwtAuthenticationConverterAdapter(
                        new KeycloakJwtAuthenticationConverter());

        http
            .csrf(ServerHttpSecurity.CsrfSpec::disable)
            .authorizeExchange(ex -> ex
                .pathMatchers("/actuator/health/**").permitAll()
                .anyExchange().authenticated())
            .oauth2ResourceServer(rs -> rs.jwt(jwt ->
                jwt.jwtAuthenticationConverter(converter)));
        return http.build();
    }
}

spring:
  cloud:
    gateway:
      default-filters:
        - TokenRelay=
      routes:
        - id: order-api
          uri: http://order-api.internal:8080
          predicates:
            - Path=/api/orders/**

@WebMvcTest(OrderController.class)
@Import(ResourceServerConfig.class)
class OrderControllerTest {

    @Autowired MockMvc mockMvc;

    @Test
    void adminEndpointRequiresPlatformAdmin() throws Exception {
        mockMvc.perform(get("/api/admin/stats")
                .with(jwt()
                    .jwt(j -> j.claim("preferred_username", "alice")
                               .claim("dept", "platform"))
                    .authorities(new SimpleGrantedAuthority("ROLE_platform-admin"))))
            .andExpect(status().isOk());
    }

    @Test
    void viewerCannotCreateOrder() throws Exception {
        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{}")
                .with(jwt().authorities(new SimpleGrantedAuthority("ROLE_order-viewer"))))
            .andExpect(status().isForbidden());
    }
}

@Test
void converterMapsRealmAndClientRoles() {
    Jwt jwt = Jwt.withTokenValue("t")
        .header("alg", "RS256")
        .claim("realm_access", Map.of("roles", List.of("platform-admin")))
        .claim("resource_access", Map.of("order-api",
                Map.of("roles", List.of("order-editor"))))
        .claim("preferred_username", "alice")
        .build();

    var token = new KeycloakJwtAuthenticationConverter().convert(jwt);

    assertThat(token.getAuthorities())
        .extracting(GrantedAuthority::getAuthority)
        .containsExactlyInAnyOrder("ROLE_platform-admin", "ROLE_order-editor");
}

logging:
  level:
    org.springframework.security: TRACE
    org.springframework.security.oauth2: TRACE