OAuth2 – @EnableResourceServer vs @EnableOAuth2Sso

1. Overview

In this tutorial, we’re going to talk about the @EnableResourceServer and @EnableOAuth2Sso annotations in Spring Security.

We’ll begin by explaining the differences between an OAuth2 Client and an OAuth2 Resource Server. Afterwards, we’ll talk a little about what these annotations can do for us and demonstrate their usage with an example using Zuul and a simple API.

For the purpose of this article, we’re going to assume some pre-existing experience with Zuul and OAuth2.

If you don’t have any or feel that a review of either one would be helpful, please refer to our quick overview on Zuul and our guide to OAuth2.

2. OAuth2 Client and Resource Server

There are four different roles within OAuth2 we need to consider:

• Resource Owner — an entity that is able to grant access to its protected resources
• Authorization Server — grants access tokens to Clients after successfully authenticating Resource Owners and obtaining their authorization
• Resource Server — a component that requires an access token to allow, or at least consider, access to its resources
• Client — an entity that is capable of obtaining access tokens from authorization servers

Annotating our configuration class with @EnableResourceServer, or @EnableOAuth2Sso, instructs Spring to configure components that transform our application into one of the latter two roles mentioned above.

The @EnableResourceServer annotation enables our application to behave as a Resource Server by configuring an OAuth2AuthenticationProcessingFilter and other equally important components.

Check out the ResourceServerSecurityConfigurer class to get a better idea on what’s being configured behind the scenes.

Conversely, the @EnableOAuth2Sso annotation transforms our application into an OAuth2 client. It instructs Spring to configure an OAuth2ClientAuthenticationProcessingFilter, along with other components that our application needs to be capable of obtaining access tokens from an authorization server.

Take a look at the SsoSecurityConfigurer class for further details on what Spring configures for us.

Combining these annotations with some properties enables us to get things up and running quickly. Let’s create two different applications to see them in action and how they can complement each other:

• Our first application is going to be our edge node, a simple Zuul application that is going to use @EnableOAuth2Sso annotation. It’s going to be responsible for authenticating users (with the help of an Authorization Server) and delegate incoming requests to other applications
• The second application is going to use @EnableResourceServer annotation and will allow access to protected resources if the incoming requests contain a valid OAuth2 access token

3. Zuul – @EnableOAuth2Sso

Let’s start by creating a Zuul application that is going to act as our edge node and is going to be responsible for authenticating users using an OAuth2 Authorization Server:

@Configuration
@EnableZuulProxy
@EnableOAuth2Sso
@Order(value = 0)
public class AppConfiguration extends WebSecurityConfigurerAdapter {

    @Autowired
    private ResourceServerTokenServices 
      resourceServerTokenServices;

    @Override
    public void configure(HttpSecurity http) throws Exception { 
        http.csrf().disable()
            .authorizeRequests()
            .antMatchers("/authorization-server-1/**",
              "/login").permitAll()
            .anyRequest().authenticated().and()
            .logout().permitAll().logoutSuccessUrl("/");
    }
}

Annotating our Zuul application with @EnableOAuth2Sso also notifies Spring to configure an OAuth2TokenRelayFilter filter. This filter retrieves previously obtained access tokens from users’ HTTP sessions and propagates them downstream.

Note that we’re also using the @Order annotation in our AppConfiguration configuration class. This is to make sure that Filters created by our WebSecurityConfigurerAdapter take precedence over Filters created by other WebSecurityConfigurerAdapters.

For example, we could annotate our Zuul application with @EnableResourceServer to support both HTTP Session identifiers and OAuth2 access tokens. However, doing so creates new Filters that by default, take precedence over the ones created by AppConfiguration class. This happens because ResouceServerConfiguration, a configuration class triggered by @EnableResourceServer, specifies a default order of 3 while WebSecurityConfigureAdapter has a default order of 100.

Before we move onto our Resource Server, we need to configure some properties:

zuul:
  routes:
    resource-server-mvc-1: /resource-server-mvc-1/**
    authorization-server-1:
      sensitiveHeaders: Authorization
      path: /authorization-server-1/**
      stripPrefix: false
  add-proxy-headers: true

security:
  basic:
    enabled: false
  oauth2:
    sso:
      loginPath: /login
    client:
      accessTokenUri: http://localhost:8769/authorization-server-1/oauth/token
      userAuthorizationUri: /authorization-server-1/oauth/authorize
      clientId: fooClient
      clientSecret: fooSecret
    resource:
      jwt:
        keyValue: "abc"
      id: fooScope
      serviceId: ${PREFIX:}resource

Without going into too much detail, using this config, we are:

• Configuring our Zuul routes and saying which headers should be added/removed before sending requests downstream.
• Setting some OAuth2 properties for our application to be able to communicate with our Authorization Server and configuring JWT with symmetric encryption.

4. API – @EnableResourceServer

Now that we have our Zuul application in place, let’s create our Resource Server:

@SpringBootApplication
@EnableResourceServer
@Controller
@RequestMapping("/")
class ResourceServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(ResourceServerApplication.class, args);
    }

    @RequestMapping(method = RequestMethod.GET)
    @ResponseBody
    public String helloWorld(Principal principal) {
        return "Hello " + principal.getName();
    }
}

It’s a simple application that exposes a single endpoint to return the name of the Principal that initiated the request.

Let’s wrap up by configuring some properties:

security:
  basic:
    enabled: false
  oauth2:
    resource:
      jwt:
        keyValue: "abc"
      id: fooScope
      service-id: ${PREFIX:}resource

Keep in mind that we need a valid access token (which is stored in the HTTP Session of the user in our edge node) to access the endpoint of our Resource Server.

5. Conclusion

In this article, we explained the differences between the @EnableOAuth2Sso and @EnableResourceServer annotations. We also demonstrated how to use them with a practical example using Zuul and a simple API.

The full implementation of this example can be found over on Github.

When running locally, we can run and test the application at http://192.168.1.67:8765/resource-server-mvc-1