Last updated: 2024-04-19

Set up Spring Boot as a resource server for Keycloak

Keycloak can be integrated into a Spring Boot application in various ways. This article describes how our application can be set up as a resource server for Keycloak. A running Keycloak server in the current version 24.0.3 with a configured client as described here is required.

Backgrounds

In the context of OAuth, resource server means that our application provides a resource - our REST API. The user has already been identified by the authorization server, so that the client possesses a token that is sent along to the resource server. Our application therefore no longer has to issue a new token, but only validate the token provided. In simplified form, the process looks as follows:

Accessing the resource server with a token

This approach makes a lot of sense with an SPA (single page application) like Angular or React: the client authenticates itself directly with Keycloak via OAuth, and our Spring Boot application is then only provided with the final token in the Authorization: Bearer ... header. The validity of the token is checked directly with Keycloak.

Spring Boot integration

For exactly this scenario, Spring Boot provides the library spring-boot-starter-oauth2-resource-server, which includes all other required libraries. After we have added this to our Gradle or Maven project, we need a single additional property.

With this setting, Spring Boot will download the certificates to verify the token on demand, in other words the first time a protected resource is accessed. If the endpoint cannot be reached at this time or the realm is not available ("bootify" in the link above), an error occurs and the authentication is canceled.

All that is missing now is our central configuration of Spring Security.

@Configuration
@EnableMethodSecurity(prePostEnabled = true)
public class OAuthSecurityConfig {

@Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        final JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(source -> mapAuthorities(source.getClaims()));
        return converter;
    }

private List<GrantedAuthority> mapAuthorities(final Map<String, Object> attributes) {
        final Map<String, Object> realmAccess =
                ((Map<String, Object>)attributes.getOrDefault("realm_access", Collections.emptyMap()));
        final Collection<String> roles =
                ((Collection<String>)realmAccess.getOrDefault("roles", Collections.emptyList()));
        return roles.stream()
                .map(role -> ((GrantedAuthority)new SimpleGrantedAuthority(role)))
                .toList();
    }

@Bean
    public SecurityFilterChain oauthFilterChain(final HttpSecurity http) throws Exception {
        return http.cors(withDefaults())
                .csrf(csrf -> csrf.disable())
                .authorizeHttpRequests(authorize -> authorize.anyRequest().permitAll())
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults()))
                .build();
    }

}

Here a bean of type SecurityFilterChain is provided, which configures our application as a resource server based on JWT via .oauth2ResourceServer(...). The bean of type JwtAuthenticationConverter is automatically picked up by Spring Boot, so that the roles are read from the realm_access.roles claim of the token - just as we have configured it in our Keycloak server. As the validity of the tokens is relatively short, changes to the roles are also passed on relatively quickly.

CSRF can be completely deactivated if our application only has a REST API. If we also have server-side forms, CSRF should still be active for these parts of the application.

With authorize.anyRequest().permitAll(), our entire application is at first accessible without a token. However, with the @EnableMethodSecurity we enable annotions to shield the RestController to be protected directly.

A simple resource available only for authenticated users

With these extensions we have successfully configured our application as a resource server!

Jump start with Bootify

In the Free plan, an executable Spring Boot application can be created directly in the browser, with your custom database schema and REST API. In the Professional plan the application can be configured as a resource server for Keycloak, so that the described setup is directly available. If required, authenticated users are also synchronized with the database and the integration tests include a configured Keycloak instance using test containers.

See Pricing
or read quickstart

‹

Supporting OAuth with Spring Boot and HTMX

Integrating Keycloak with Angular and Spring Boot

›

Create new account

Log in with existing account

Reset your password

Set up Spring Boot as a resource server for Keycloak

Backgrounds

Spring Boot integration

Jump start with Bootify

General error