Security Top

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE

1. Introduction

OAuth is an open standard that describes a process of authorization. It can be used to authorize user access to an API. For example, a REST API can restrict access only for registered users with a proper role.

An OAuth authorization server is responsible for authenticating the users and issuing access tokens containing the user data and proper access policies.

In this tutorial, we'll implement a simple OAuth application using the Spring Security OAuth Authorization Server project.

In the process, we'll create a client-server application that will fetch a list of Baeldung articles from a REST API. Both the client services and server services will require an OAuth authentication.

2. Authorization Server Implementation

Let's start by looking at the OAuth authorization server configuration. It'll serve as an authentication source for both the article resource and client servers.

2.1. Dependencies

First, we'll need to add a few dependencies to our pom.xml file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-authorization-server</artifactId>
    <version>0.2.0</version>
</dependency>

2.2. Configuration

Now, let's configure the port that our auth server will run on by setting the server.port property in the application.yml file:

server:
  port: 9000

After that, we can move to the Spring beans configuration. First, we'll need a @Configuration class where we'll create a few OAuth-specific beans. The first one will be the repository of client services. In our example, we'll have a single client, created using the RegisteredClient builder class:

@Configuration
@Import(OAuth2AuthorizationServerConfiguration.class)
public class AuthorizationServerConfig {
    @Bean
    public RegisteredClientRepository registeredClientRepository() {
        RegisteredClient registeredClient = RegisteredClient.withId(UUID.randomUUID().toString())
          .clientId("articles-client")
          .clientSecret("{noop}secret")
          .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
          .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
          .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
          .redirectUri("http://127.0.0.1:8080/login/oauth2/code/articles-client-oidc")
          .redirectUri("http://127.0.0.1:8080/authorized")
          .scope(OidcScopes.OPENID)
          .scope("articles.read")
          .build();
        return new InMemoryRegisteredClientRepository(registeredClient);
    }
}

The properties we're configuring are:

  • Client ID – Spring will use it to identify which client is trying to access the resource
  • Client secret code – a secret known to the client and server that provides trust between the two
  • Authentication method – in our case, we'll use basic authentication which is just a username and password
  • Authorization grant type – we want to allow the client to generate both an authorization code and a refresh token
  • Redirect URI – the client will use it in a redirect-based flow
  • Scope – this parameter defines authorizations that the client may have. In our case, we'll the required OidcScopes.OPENID and our custom one – articles. read

Next, let's configure a bean to apply the default OAuth security and generate a default form login page:

@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
public SecurityFilterChain authServerSecurityFilterChain(HttpSecurity http) throws Exception {
    OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
    return http.formLogin(Customizer.withDefaults()).build();
}

Each authorization server needs its signing key for tokens to keep a proper boundary between security domains. Let's generate a 2048-byte RSA key:

@Bean
public JWKSource<SecurityContext> jwkSource() {
    RSAKey rsaKey = generateRsa();
    JWKSet jwkSet = new JWKSet(rsaKey);
    return (jwkSelector, securityContext) -> jwkSelector.select(jwkSet);
}

private static RSAKey generateRsa() {
    KeyPair keyPair = generateRsaKey();
    RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
    RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
    return new RSAKey.Builder(publicKey)
      .privateKey(privateKey)
      .keyID(UUID.randomUUID().toString())
      .build();
}

private static KeyPair generateRsaKey() {
    KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
    keyPairGenerator.initialize(2048);
    return keyPairGenerator.generateKeyPair();
}

Except for the signing key, each authorization server needs to have a unique issuer URL as well. We'll set it up as a localhost alias for http://auth-server on port 9000 by creating the ProviderSettings bean:

@Bean
public ProviderSettings providerSettings() {
    return ProviderSettings.builder()
      .issuer("http://auth-server:9000")
      .build();
}

Additionally, we'll add an “127.0.0.1 auth-server” entry in our /etc/hosts file. This allows us to run the client and the auth server on our local machine and avoids problems with session cookie overwrites between the two.

Finally, we'll enable the Spring web security module with an @EnableWebSecurity annotated configuration class:

@EnableWebSecurity
public class DefaultSecurityConfig {

    @Bean
    SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeRequests(authorizeRequests ->
          authorizeRequests.anyRequest().authenticated()
        )
          .formLogin(withDefaults());
        return http.build();
    }

    // ...
}

Here, we're calling authorizeRequests.anyRequest().authenticated() to require authentication for all requests, and we're providing a form-based authentication by invoking the formLogin(defaults()) method.

Additionally, we'll define a set of example users that we'll use for testing. For the sake of this example, let's create a repository with just a single admin user:

@Bean
UserDetailsService users() {
    UserDetails user = User.withDefaultPasswordEncoder()
      .username("admin")
      .password("password")
      .build();
    return new InMemoryUserDetailsManager(user);
}

3. Resource Server

Now, we'll create a resource server that will return a list of articles from a GET endpoint. The endpoints should allow only requests that are authenticated against our OAuth server.

3.1. Dependencies

First, let's include the required dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
    <version>2.5.4</version>
</dependency>

3.2. Configuration

Before we start with the implementation code, we should configure some properties in the application.yml file. The first one is the server port:

server:
  port: 8090

Next, it's time for the security configuration. We need to set up the proper URL for our authentication server with the host and the port we've configured in the ProviderSettings bean earlier:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://auth-server:9000

Now, we can set up our web security configuration. Again, we want to explicitly say that every request to article resources should be authorized and have the proper articles.read authority:

@EnableWebSecurity
public class ResourceServerConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.mvcMatcher("/articles/**")
          .authorizeRequests()
          .mvcMatchers("/articles/**")
          .access("hasAuthority('SCOPE_articles.read')")
          .and()
          .oauth2ResourceServer()
          .jwt();
        return http.build();
    }
}

As shown here, we're also invoking the oauth2ResourceServer() method, which will configure the OAuth server connection based on the application.yml configuration.

3.3. Articles Controller

Finally, we'll create a REST controller that will return a list of articles under the GET /articles endpoint:

@RestController
public class ArticlesController {

    @GetMapping("/articles")
    public String[] getArticles() {
        return new String[] { "Article 1", "Article 2", "Article 3" };
    }
}

4. API Client

For the last part, we'll create a REST API client that will fetch the list of articles from the resource server.

4.1. Dependencies

To start, let's include the needed dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
    <version>2.5.4</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webflux</artifactId>
    <version>5.3.9</version>
</dependency>
<dependency>
    <groupId>io.projectreactor.netty</groupId>
    <artifactId>reactor-netty</artifactId>
    <version>1.0.9</version>
</dependency>

4.2. Configuration

As we did earlier, we'll define some configuration properties for authentication purposes:

server:
  port: 8080

spring:
  security:
    oauth2:
      client:
        registration:
          articles-client-oidc:
            provider: spring
            client-id: articles-client
            client-secret: secret
            authorization-grant-type: authorization_code
            redirect-uri: "http://127.0.0.1:8080/login/oauth2/code/{registrationId}"
            scope: openid
            client-name: articles-client-oidc
          articles-client-authorization-code:
            provider: spring
            client-id: articles-client
            client-secret: secret
            authorization-grant-type: authorization_code
            redirect-uri: "http://127.0.0.1:8080/authorized"
            scope: articles.read
            client-name: articles-client-authorization-code
        provider:
          spring:
            issuer-uri: http://auth-server:9000

Now, let's create a WebClient instance to perform HTTP requests to our resource server. We'll use the standard implementation with just one addition of the OAuth authorization filter:

@Bean
WebClient webClient(OAuth2AuthorizedClientManager authorizedClientManager) {
    ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2Client =
      new ServletOAuth2AuthorizedClientExchangeFilterFunction(authorizedClientManager);
    return WebClient.builder()
      .apply(oauth2Client.oauth2Configuration())
      .build();
}

The WebClient requires an OAuth2AuthorizedClientManager as a dependency. Let's create a default implementation:

@Bean
OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clientRegistrationRepository,
        OAuth2AuthorizedClientRepository authorizedClientRepository) {

    OAuth2AuthorizedClientProvider authorizedClientProvider =
      OAuth2AuthorizedClientProviderBuilder.builder()
        .authorizationCode()
        .refreshToken()
        .build();
    DefaultOAuth2AuthorizedClientManager authorizedClientManager = new DefaultOAuth2AuthorizedClientManager(
      clientRegistrationRepository, authorizedClientRepository);
    authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);

    return authorizedClientManager;
}

Lastly, we'll configure web security:

@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
          .authorizeRequests(authorizeRequests ->
            authorizeRequests.anyRequest().authenticated()
          )
          .oauth2Login(oauth2Login ->
            oauth2Login.loginPage("/oauth2/authorization/articles-client-oidc"))
          .oauth2Client(withDefaults());
        return http.build();
    }
}

Here, as well as in other servers, we'll need every request to be authenticated. Additionally, we need to configure the login page URL (defined in .yml config) and the OAuth client.

4.3. Articles Client Controller

Finally, we can create the data access controller. We'll use the previously configured WebClient to send an HTTP request to our resource server:

@RestController
public class ArticlesController {

    private WebClient webClient;

    @GetMapping(value = "/articles")
    public String[] getArticles(
      @RegisteredOAuth2AuthorizedClient("articles-client-authorization-code") OAuth2AuthorizedClient authorizedClient
    ) {
        return this.webClient
          .get()
          .uri("http://127.0.0.1:8090/articles")
          .attributes(oauth2AuthorizedClient(authorizedClient))
          .retrieve()
          .bodyToMono(String[].class)
          .block();
    }
}

In the above example, we're taking the OAuth authorization token from the request in a form of OAuth2AuthorizedClient class. It's automatically bound by Spring using the @RegisterdOAuth2AuthorizedClient annotation with proper identification. In our case, it's pulled from the article-client-authorizaiton-code that we configured previously in the .yml file.

This authorization token is further passed to the HTTP request.

4.4. Accessing the Articles List

Now, when we go into the browser and try to access the http://127.0.0.1:8080/articles page, we'll be automatically redirected to the OAuth server login page under http://auth-server:9000/login URL:

After providing the proper username and password, the authorization server will redirect us back to the requested URL – the list of articles.

Further requests to the articles endpoint won't require logging in, as the access token will be stored in a cookie.

5. Conclusion

In this article, we've learned how to set up, configure, and use the Spring Security OAuth Authorization Server.

As always, all the source code is available over on GitHub.

Security bottom

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

>> CHECK OUT THE COURSE
Generic footer banner
6 Comments
Oldest
Newest
Inline Feedbacks
View all comments
Comments are closed on this article!