Spring Cloud OAuth

In this blog post we will create a secure API for external access, using OAuth 2.0, to the microservices we created inPart 1 and Part 2.

For information about OAuth 2.0 either see introductory material Parecki - OAuth 2 Simplified and Jenkov - OAuth 2.0 Tutorial or the specification IETF RFC 6749.

We will add a new microservice, product-api, that will act as the external API (a Resource Server in OAuth terminology) and we will expose its services through the edge server that we introduced in Part 1 acting as a token relay, i.e. forwarding OAuth access tokens from the client to the resource server. We will also add an OAuth Authorization Server and an OAuth client, i.e. service consumer, we will continue to use cURL.

The system landscape from Part 2 will be complemented with the new OAuth components (marked with a red line):

We will demonstrate how a client can use any of the four standard authorization grant flows to get an access token from the authorization server and then use the access token to make a secure request to the resource server, i.e. the API.

NOTES:

• Protecting external API’s is nothing specific to microservices, so this blog post is applicable to any architecture where there is a need to secure external API’s using OAuth 2.0!

• We will provide a lightweight OAuth authorization server only useful for development and testing. In a real world usage it needs to be replaced, e.g. by an API platform or by delegating the sign in and authorization process to social networks such as Facebook or Twitter.

• We are on purpose only using HTTP in this blog post to reduce complexity. In any real world usage of OAuth all traffic should be protected using TLS, i.e. HTTPS!

• As in the previous posts we emphasize the differences between microservices and monolithic applications by running each service in a separate microservice, i.e. in separate processes.

1. BUILD FROM SOURCE

As in Part 2 we use Java SE 8, Git and Gradle. So, to access the source code and build it perform:

git clone https://github.com/callistaenterprise/blog-microservices.git
cd blog-microservices
git checkout -b B3 M3.1
./build-all.sh

If you are on Windows you can execute the corresponding bat-file build-all.bat!

Two new source code components have been added since Part 2, an OAuth Authorization Server, auth-server, and the OAuth Resource Server, product-api-service:

The build should result in ten log messages that all says:

BUILD SUCCESSFUL

1. SOURCE CODE WALKTHROUGH

Let’s look into how the two new components are implemented and how the edge server is updated to be able to relay the OAuth access tokens. We will also change the URL for the API to make it a bit more convenient to use.

2.1 GRADLE DEPENDENCIES

To be able to use OAuth 2.0 we will bring in the open source projects spring-cloud-security and spring-security-oauth2 with the following dependencies.

For the auth-server:

    compile("org.springframework.boot:spring-boot-starter-security")
    compile("org.springframework.security.oauth:spring-security-oauth2:2.0.6.RELEASE")

For full source code see auth-server/build.gradle.

For the product-api-service:

    compile("org.springframework.cloud:spring-cloud-starter-security:1.0.0.RELEASE")
    compile("org.springframework.security.oauth:spring-security-oauth2:2.0.6.RELEASE")

For full source code see product-api-service/build.gradle.

2.2 AUTH-SERVER

The implementation of the authorization server is straight forward. It is brought to life using an annotation, @EnableAuthorizationServer. Then we use a configuration class to register (in-memory only) the approved client applications, specifying client-id, client-secret, allowed grant flows and scopes:

  @EnableAuthorizationServer
  protected static class OAuth2Config extends AuthorizationServerConfigurerAdapter {

    @Override
    public void configure(ClientDetailsServiceConfigurer clients) throws Exception {
      clients.inMemory()
        .withClient("acme")
        .secret("acmesecret")
        .authorizedGrantTypes("authorization_code", "refresh_token", "implicit", "password", "client_credentials")
        .scopes("webshop");
    }
  }

This approach obviously only works for development and test to simulate a client application registration process provided by real world OAuth Authorization Servers, e.g. LinkedIn or GitHub.

For full source code see AuthserverApplication.java.

Registration of users (Resource Owner in OAuth terminology), simulating a real world Identity Provider (IdP), is done by adding one line per user in the file application.properties, e.g.:

security.user.password=password

For full source code see application.properties.

The implementation also comes with two simple web based user interfaces for user authentication and user consent, see the source code for details.

2.3 PRODUCT-API-SERVICE

To make our API-implementation act as a OAuth Resource Server we only need to annotate the main-method with the @EnableOAuth2Resource-annotation:

@EnableOAuth2Resource
public class ProductApiServiceApplication {

For full source code see ProductApiServiceApplication.java.

The implementation of the API-service is very similar to the composite service in Part 2. To be able to verify that OAuth works we have added logging of the user-id and the access token:

@RequestMapping("/{productId}")
    @HystrixCommand(fallbackMethod = "defaultProductComposite")
    public ResponseEntity<String> getProductComposite(
        @PathVariable int productId,
        @RequestHeader(value="Authorization") String authorizationHeader,
        Principal currentUser) {

        LOG.info("ProductApi: User={}, Auth={}, called with productId={}",
          currentUser.getName(), authorizationHeader, productId);
        ...

NOTES:

• Spring MVC will fill in the extra parameters for the current user and the authorization header automatically.

• We have removed the uri /product from the @RequestMapping to be able to get a more compact URL when using the edge server since it will add a /product prefix to the url to be able to route the request to the correct service.

• Writing access tokens to the log is probably not to recommend from a security perspective in a real world application.

2.4 UPDATES TO THE EDGE SERVER

Finally we need to make the edge server forward the OAuth access tokens down to the API-service. Fortunately this is actually already the default behavior, so we don’t need to do anything in this case