Spring Security OAuth2 Resource Server: JWT, Scopes & Token Introspection

You've set up Spring Security before — form login, in-memory users, the works. Then your team adopts microservices and suddenly every service needs to validate tokens issued by a central authorization server. You add a Bearer token check by hand, store user info in a custom header, and pray nothing changes. It breaks in staging because you forgot to update the JWKS URI. This is the production pain that spring-boot-starter-oauth2-resource-server was built to eliminate.

The OAuth2 Resource Server starter ships with everything needed to validate JWTs cryptographically, decode claims into a JwtAuthenticationToken, and expose those claims to your @PreAuthorize annotations. You get automatic JWKS rotation, clock skew handling, and a security filter chain that rejects unsigned or expired tokens before your business logic ever runs.

In microservice architectures the story gets more nuanced. A gateway receives a user token and needs to relay it downstream. Downstream services need to validate it independently without coupling to the gateway. Spring's token relay support and SecurityContext propagation handle this cleanly — but only if you configure the resource server correctly on every service.

Opaque tokens add another dimension. When the authorization server cannot embed claims in the token (for example, when the token is a random UUID stored server-side), each resource server must call the introspection endpoint. Spring Security 6 supports both flows with nearly identical configuration.

This guide walks through production-ready Resource Server configuration: NimbusJwtDecoder setup, JWKS rotation, scope extraction, custom claims conversion, OAuth2 Login integration with GitHub and Google, and token relay patterns for microservices. Every code sample runs on Spring Boot 3.x with Java 17+.

Setting Up the OAuth2 Resource Server

Adding spring-boot-starter-oauth2-resource-server to your pom.xml pulls in Spring Security's full OAuth2 stack including NimbusJwtDecoder, JWT validation filters, and auto-configuration. With a single property — spring.security.oauth2.resourceserver.jwt.issuer-uri — Spring Boot fetches the OpenID Connect discovery document, extracts the JWKS URI, and configures the decoder automatically.

For production, always declare a SecurityFilterChain bean explicitly rather than relying on the auto-configured one. This gives you control over which endpoints require authentication, what scopes are needed, and how exceptions are handled. The auto-configured chain requires every endpoint to be authenticated — a common surprise when you add an /actuator/health endpoint.

The oauth2ResourceServer DSL in Spring Security 6 uses lambdas. Pass a customizer to jwt() to override the decoder, set audience validation, or add custom claim validators. The JwtDecoder bean is separate from the filter chain — you can override just the decoder while keeping the rest of the auto-configuration.

Always set audiences validation in production. Without it, a token issued for a different resource server (but signed by the same IdP) is accepted by your service. Use JwtValidators.createDefaultWithIssuer() combined with new AudienceValidator(Set.of("my-api")) and wrap both in DelegatingOAuth2TokenValidator.

Scope-Based Authorization with @PreAuthorize

Spring Security's method security integrates cleanly with OAuth2 scopes. Once you enable @EnableMethodSecurity, you can place @PreAuthorize("hasAuthority('SCOPE_read')") on service methods, controllers, or even repository methods. This pushes authorization logic close to the domain rather than scattering it across the security filter chain configuration.

For complex authorization rules combining scopes with business data (e.g., a user can only read their own orders), use @PostAuthorize or Spring Security's @PreAuthorize with SpEL expressions accessing the Authentication object. Extract the subject (sub) claim via authentication.name or directly from the JwtAuthenticationToken.

A common pattern is to create a custom @CurrentUser annotation backed by @AuthenticationPrincipal. This gives controller methods clean access to the JWT claims without manually extracting from the SecurityContext. Pair this with a custom principal class that wraps the JWT and exposes typed claim accessors.

Scope hierarchies are not natively supported by Spring Security's OAuth2 layer, but you can implement them by expanding scopes in a custom JwtGrantedAuthoritiesConverter. For example, admin scope implicitly grants read and write — your converter can synthesize all implied authorities when it detects the admin scope.

Opaque Token Introspection

When the authorization server issues random reference tokens instead of JWTs, the resource server cannot validate them locally. Spring Security supports RFC 7662 introspection out of the box. Configure spring.security.oauth2.resourceserver.opaquetoken.introspection-uri, client-id, and client-secret, then switch the DSL to .oauth2ResourceServer(oauth2 -> oauth2.opaqueToken(...)). Spring posts the token to the introspection endpoint and maps the response to OAuth2AuthenticatedPrincipal.

The cost is a network round-trip per request. In high-throughput services this is significant. Mitigate with a short-lived local cache: wrap the default OpaqueTokenIntrospector with a Caffeine-backed decorator that caches introspection responses keyed by token hash for up to the token's remaining TTL.

Custom claims in the introspection response are automatically available on OAuth2AuthenticatedPrincipal.getAttribute("custom_claim"). If you need to transform introspection response claims into GrantedAuthority objects, implement a custom OpaqueTokenIntrospector that delegates to NimbusOpaqueTokenIntrospector and then post-processes the result.

Security note: always hash the token before using it as a cache key. Storing raw tokens in memory or logs is a security anti-pattern — if your cache is dumped, attackers gain valid tokens.

OAuth2 Login with GitHub and Google

Spring Boot's spring-boot-starter-oauth2-client enables OAuth2 Login — delegating user authentication to external providers like GitHub or Google. Unlike the Resource Server (which validates tokens), OAuth2 Login initiates the authorization code flow, exchanges the code for an access token, fetches user info, and creates a Spring Security session backed by OAuth2User or OidcUser.

Register each provider under spring.security.oauth2.client.registration. Spring Boot pre-configures commonOAuth2Provider entries for Google, GitHub, Facebook, and Okta — you only need to supply client-id and client-secret. For custom IdPs, define a provider block with authorization URI, token URI, and user-info URI.

Extract the authenticated user's information in controllers using @AuthenticationPrincipal OAuth2User for standard OAuth2 providers or @AuthenticationPrincipal OidcUser for OIDC providers like Google. The OidcUser exposes standard claims directly (user.getEmail(), user.getName()) without manual attribute mapping.

For microservices combining OAuth2 Login at the gateway with JWT-based downstream services, implement token exchange: after the user authenticates via OAuth2 Login, issue an internal JWT containing the user's id, email, and roles, then propagate that JWT in service-to-service calls. This decouples downstream services from the external OAuth2 provider.

Token Relay in Microservices

In a microservice architecture, the gateway authenticates the user and receives a JWT. Downstream services need that token to authorize requests independently. Token relay means forwarding the original access token from the incoming request to outgoing service calls.

Spring Security's OAuth2AuthorizedClientManager combined with ServerOAuth2AuthorizedClientExchangeFilterFunction (for reactive stacks) or a ClientHttpRequestInterceptor (for servlet stacks) handles token relay automatically for client credentials flow. For user-context relay, extract the token from the SecurityContext and inject it into WebClient or RestTemplate headers.

The spring-cloud-starter-gateway with TokenRelayGatewayFilterFactory provides turnkey relay: add - TokenRelay= to your route filters and the gateway appends Authorization: Bearer <token> to all proxied requests. Downstream services configured as Resource Servers validate the token independently.

For service-to-service calls without user context (batch jobs, background tasks), use the Client Credentials grant. Configure a separate OAuth2 client registration with authorization-grant-type: client_credentials and inject OAuth2AuthorizedClientManager to obtain and auto-refresh tokens. The manager handles token expiry transparently.

Testing OAuth2 Resource Server Endpoints

Testing secured endpoints requires injecting mock tokens or using Spring Security's test support. @WithMockUser does not work for OAuth2 Resource Servers because it creates a UsernamePasswordAuthenticationToken, not a JwtAuthenticationToken. Use SecurityMockMvcRequestPostProcessors.jwt() instead, which builds a real JwtAuthenticationToken with configurable claims and authorities.

For integration tests, @SpringBootTest with @AutoConfigureMockMvc combined with jwt() post-processor gives full coverage of the security filter chain without a real authorization server. You can set specific JWT claims, authorities, and subject to simulate different user roles.

For actual token validation (testing the decoder configuration), use Testcontainers with a real Keycloak instance or WireMock to stub the JWKS endpoint and issue real JWTs signed with a test key. This validates your audience and issuer configuration end-to-end.

Spring Security's @WithSecurityContext allows creating custom annotations that combine jwt() setup with role assignments, making tests readable: @WithJwtUser(subject = "user-123", scopes = {"orders:read"}) is self-documenting and avoids repetitive jwt().jwt(...) builder chains in every test.

Why You Need a Custom Token Converter (and When You Don't)

The default Spring Security token converter works fine for standard claims. But real auth servers send custom claims—tenant IDs, custom roles, or department codes. You cannot rely on the default mapper when your authorization server returns something like { "sub": "user", "x-org": "acme", "x-roles": ["admin"] }. The default converter will silently drop those fields. You must write a custom OAuth2TokenConverter that maps those claims into your Authentication object. This is not optional. If you don't do it, your @PreAuthorize annotations will see an empty authority list, and every request will be denied. The fix is a simple OAuth2TokenValidator and OAuth2TokenConverter implementation. Start with a claim set adapter that reads your custom fields and populates GrantedAuthority objects. Then register it as a bean. Nothing else changes.

// io.thecodeforge — java tutorial
@Component
public class CustomTokenConverter implements ReactiveOAuth2TokenConverter<Jwt, Mono<AbstractAuthenticationToken>> {

    @Override
    public Mono<AbstractAuthenticationToken> convert(Jwt jwt) {
        Map<String, Object> claims = jwt.getClaims();
        String org = (String) claims.getOrDefault("x-org", "default");
        List<String> roles = (List<String>) claims.getOrDefault("x-roles", List.of());
        
        Set<GrantedAuthority> authorities = roles.stream()
            .map(SimpleGrantedAuthority::new)
            .collect(Collectors.toSet());
        authorities.add(new SimpleGrantedAuthority("ORG_" + org));
        
        return Mono.just(new JwtAuthenticationToken(jwt, authorities));
    }
}

OAuth2 Client Credentials Flow: The Server-to-Server Pattern

Most tutorials show the authorization code flow for user login. But microservices talk to each other using the client credentials flow—no user involved. Your service needs a client ID and client secret, not a browser redirect. Configure a ClientRegistration with authorizationGrantType=CLIENT_CREDENTIALS and a tokenUri. Then use OAuth2AuthorizedClientManager to get a token before calling another service. This flow is stateless and does not require user consent. The token expires. Your code must handle token refresh automatically. Spring's WebClient with the ServletOAuth2AuthorizedClientExchangeFilterFunction does this for you. You just need one bean: OAuth2AuthorizedClientManager. Wire it into your WebClient builder. Then every outbound request gets a fresh token. No manual token fetching.

// io.thecodeforge — java tutorial
@Configuration
public class ClientCredentialsConfig {

    @Bean
    public OAuth2AuthorizedClientManager authorizedClientManager(
            ClientRegistrationRepository clientRegistrations,
            OAuth2AuthorizedClientRepository authorizedClients) {
        
        OAuth2AuthorizedClientProvider provider = 
            OAuth2AuthorizedClientProviderBuilder.builder()
                .clientCredentials()
                .build();
        
        DefaultOAuth2AuthorizedClientManager manager = 
            new DefaultOAuth2AuthorizedClientManager(clientRegistrations, authorizedClients);
        manager.setAuthorizedClientProvider(provider);
        return manager;
    }
}