InSource Software

ZeroMQ with Spring Boot, Part 2

Sat, 09 Jan 2021 00:00:00 +0000

Introduction

In the previous article, we discussed using a heavy-weight broker for communication in a microservices architecture versus a more zen/zero/minimal approach. In this article, we’ll explore some examples and practical applications and look at how well it might actually work.

Use Case - Distributed Logging

Let’s say we want to build a distributed logging solution for our distributed architecture. Further, let’s make it more difficult and say that our organization has placed limitations on us that we can either use our cloud platform’s fire-hose as input and get this for free, or build a solution that requires no additional infrastructure to stand up.

Now, the only readily available option our ops team has given us is to use the fire-hose. Effectively, this means using the STDOUT stream from each of our JVMs, Node.js servers, what have you, to go directly to the logging server, for example a Splunk cluster. However, this solution is ignorant to the nature of our logs. On the JVM, errors in the form of a stack trace are structured as multiple lines written to STDOUT. There would be no clean way to view all lines of the stack trace as a single record in Splunk. True story.

Let’s build a solution

Logging Adapter

Let’s say you’re using slf4j to log to a logback appender, which logs to STDOUT. This is the default in Spring Boot. Most teams won’t ever go beyond this unless forced to. Here’s an intentionally over-simplified logback appender to log to STDOUT:

public class ConsoleAppender implements Appender<ILoggingEvent> {
    ...

    public void doAppend(ILoggingEvent event) {
        System.out.println(event.getMessage());
    }
}

Let’s replace this with Spring ZeroMQ. To do that, we will need a ZmqTemplate. For simplicity, let’s assume we can take it as a constructor parameter.

public class ZmqAppender implements Appender<ILoggingEvent> {
    private final ZmqTemplate zmqTemplate;

    public ZmqAppender(ZmqTemplate zmqTemplate) {
        this.zmqTemplate = zmqTemplate;
    }

    public void doAppend(ILoggingEvent event) {
        zmqTemplate.send(event.getMessage());
    }
}

Now at this point, we aren’t doing much of anything impressive. We’re probably dropping the stack trace (if any) on the floor, and we throw away most of the useful data of the event as well, in favor of capturing only the log message. We’ll address this in a future post if there’s interest.

From here, we must ask ourselves: “How do we get this data into Splunk?” Remember that ZmqTemplate? Configure it this way:

@Configuration
@EnableZmqPublisher
public class PublisherConfiguration {
    @Bean
    public ZmqTemplate zmqTemplate() {
        ZmqTemplate zmqTemplate = new ZmqTemplate();
        zmqTemplate.setTopic("logs");
        zmqTemplate.setRoutingKey("LoggingEvent");
        zmqTemplate.setMessageConverter(new LoggingEventMessageConverter());

        return zmqTemplate;
    }
}

And configure the publisher thread in your application.yml:

zmq:
  publisher:
    host: log-service.apps.mydomain.com
    port: 5678
    topics:
      - logs

So we probably need some kind of highly-available broker to slurp in those logs, right? We could do that, but our ops team has said that’s a non-starter. Curse them! Ok, what else can we do?

I’m guessing you already have a microservice somewhere in your architecture that isn’t doing anything most of the time. In a recent project, we had a remote deposit capture service sitting there that occasionally processed deposits from a mobile phone. The rest of the time, it was bored. Let’s just package up a library that turns that service into a logging service.

Logging Service

In the config above, notice we referenced a hypothetical service called log-service. Using your cloud platform of choice, go ahead and bind that URL to your bored microservice. In our case, log-service.apps.mydomain.com —> remote-deposit-service.apps.mydomain.com.

Now, we create a project that utilizes Spring Boot dependencies (the build file looks pretty much just like a spring boot app minus the spring boot plugin), but isn’t itself a microservice. Call it a micro library.

Add a src/main/resources/META-INF/spring.factories with the following:

org.springboot.boot.autoconfigure.EnableAutoConfiguration=\
com.mydomain.logging.autoconfigure.LoggingAutoConfiguration

Here’s the LoggingAutoConfiguration class:

@Configuration
@EnableZmqSubscriber
public class LoggingAutoConfiguration {
    @Bean
    public LoggingSubscriber loggingSubscriber() {
        return new LoggingSubscriber();
    }

    @Bean
    public MessageConverter messageConverter() {
        return new LoggingEventMessageConverter();
    }
}

Note: The @EnableZmqSubscriber above doesn't actually work right now. You'll need to add zmq.subscriber.enabled: true in your application.yml for now. This will be fixed in a future release.

Implementing the LoggingEventMessageConverter is slightly beyond the scope of this article. However, refer to this project for a way to generate code that works with Spring ZeroMQ.

We just need a LoggingSubscriber to finish it out:

@ZmqSubscriber({
    @QueueBinding(topic = "logs", key = "LoggingEvent", queue = "splunk-logs")
})
public class LoggingSubscriber {
    @ZmqHandler
    public void onLoggingEvent(LoggingEvent event) {
        // Send log data to Splunk...
    }
}

Sadly, I will not be covering how to actually put the log data into Splunk. It is just a convenient use-case and example. You will have to do that work yourself.

Now, just drop this jar into the microservice that needs a second job (think sand-bucket holder). If you find that you can’t afford to tax this service with the job any longer, it takes less than 5 minutes to move it to another. If you can’t find anything available that has spare compute to do the job, then just stand up a brand new microservice to do it. Takes another 5 minutes. In this way, you are embracing the ZeroMQ philosophy (and just a darn good philosophy in general) that if you start simple, and do the next right thing, you will always find a simple path forward to the next one, and so on.

But will it be worth it?

Does it work?

To answer whether or not this solution will work well in practice, first consider the alternative. In order to do this in a “traditional way,” we would either need a solution handed to us by our ops team (please don’t count on this, though thank them if they provide one to you), or we would need to convince our organization to buy one for us. Buying a logging solution (they’ve already paid for Splunk in this example), is likely not an option. Why do they hire engineers to solve problems for them, if the engineers say “It’s not something I can solve. Just buy something.” That’s ridiculous. Yet all too common.

Another alternative would be to demand a message broker. That’s a fine option. But how much would it save you? Answer: Nothing. It actually costs you something extra. And it’s the same amount of work. Yet you don’t get near the same flexibility. You aren’t in complete control of your architecture. You’re now reliant on the ops team (remember the one who refused to provide a solution in the first place?) to maintain the broker. It’s OK… but not a great place to be if you don’t need to be there. I prefer to be in complete control over the entire architecture, and let the ops team handle non-solution-oriented infrastructure only. Trust me, they prefer it that way too.

Conclusion

In this article, we’ve learned how to solve a common and annoying problem with distributed logging by using spare compute, a bit of creativity, and Spring Boot without the use of a message broker. We were able to leverage in-spring-zeromq to do a job that seemed daunting, and spend less than hours on the solution. Next time, we’ll examine another interesting use case involving user activity, to find out what our users are up to.

ZeroMQ with Spring Boot

Fri, 08 Jan 2021 00:00:00 +0000

Introduction

In the previous article, we discussed how to use Zuul’s reverse-proxy functionality to propagate session information in a stateless way. In this article, we’ll discuss something entirely different, namely a library for getting more mileage for your messaging buck.

New Solutions to Old Problems

In the last year, I’ve worked heavily on some side projects that required thinking outside the box a bit in terms of minimizing dependencies and setup. When wanting to deploy an efficient and elegant solution to a messy problem, the last thing I wanted to tell a client or potential customer was that they had to spend more or learn additional tools just to use my solution. One thing that comes up a lot when connecting distributed architectures together is a communication layer.

There are a lot of options for this (though the obsession with messaging tools has died down a bit as microservices have become more mainstream, and AI and ML and other data-centric tech took center stage in the last few years). What I’ve seen working for a large private bank here in the midwestern U.S. is a fairly 1-size-fits-all approach. Just pick a single, decently good messaging platform, and bake it into your operational service offerings for all the developers in your organization to pull into their projects and use in any way they see fit. Normally, I’d be fine with this, as an enterprise knows what they want, and if it’s a good tool, then widespread adoption just makes it cheaper, easier to reuse, and lowers the onboarding and maintenance burden considerably.

(It’s worth mentioning at this point that not all is sunshine and roses in the messaging garden. More on this later.)

What if you want to develop a more generalized tool that doesn’t cost a fortune, yet lowers development costs, saves cycle time, hardware resources, and all the other niceties you want in a fancy sales pitch? When it comes to messaging tools, most in the (JVM) microservices circuit will probably go with Kafka or RabbitMQ, with RabbitMQ being possibly the more common choice (depending on the use case and the organization). After all, it’s free and open source of course. It seems well accepted and well understood. Better yet, it has awesome support in most modern frameworks and cloud ecosystems. So why not use it?

I’m not going to sell you on that point. Let’s just look at an alternative, and you be the judge.

ZeroMQ for connectivity

I won’t say much here for why or why not choose ZeroMQ as a technology for your connectivity needs. If you’re curious, you can check out the ZeroMQ Guide for an in-depth look at this technology. Just know, it’s not necessarily going to be the new hotness or fastest growing open source library in 2021. But it’s been around a long time, and is steadily growing in maturity, and solidly proves itself time and time again as an approachable tool for connecting distributed architectures.

0MQ also has an amazing and vibrant community which is incredibly accepting, open and approachable. I love it because I don’t have time to compete with a lot of hot-shot committers who are all over things because they don’t have anything else to do. Good for them, but I need a community that wants whatever I have time to put out there. It’s so cool!

Introducing Spring ZeroMQ

With that being said, I’d like to introduce a project that I released yesterday evening on Maven Central, in-spring-zeromq. Check out the README for some getting started info on the library.

A quick background is in order. I mentioned RabbitMQ. I like RabbitMQ actually. It’s nice. It has worked well in the simple use cases we’ve used it for in a microservices architecture. What I really like about RabbitMQ is the support bolstering it has gotten in the Spring community with Spring AMQP.

Fun fact, did you know that iMatix, the company founded by Pieter Hintjens, was the initial firm contracted by JPMorgan Chase to build AMQP?

What I don’t necessarily like is the need for a broker when I’m doing simple communication patterns. Not that ZeroMQ is only well-suited for simple communication patterns. But it feels kind of ironic that RabbitMQ’s slogan is “Messaging that just works” when you have to set up (or pay for a sidecar service to use) a broker. By definition, that does not “just work.” It requires extra work… to work. Or extra money.

Anyway, I wanted to create a ZeroMQ programming model in Spring that matched the ease-of-use of Spring AMQP. While I wouldn’t say this library approaches the level of sophistication of spring-amqp, I wanted to lay a foundation built against the same idea. Namely, when I’m building enterprise software, I don’t want to stop to have to think about how to write event loops, socket communication, and complex protocols just to send messages between two pieces. Not every part of my architecture deserves re-inventing the wheel every time I run into a connectivity problem needing to be solved. And yet, I don’t want to have to be tied to a message broker either. I want an architecture that can evolve in micro-units, like the ZeroMQ programs Pieter outlines in the ZeroMQ Guide (you really should read it).

What can I do with this?

Come back next time, for an in-depth look at in-spring-zeromq, a little library for hiding ZeroMQ behind a protective enterprise development blanket (on the JVM).

Check out the library now! Spring ZeroMQ

Conclusion

In this article, we’ve learned… well, nothing really. Hopefully we’ll get to learn a bunch next time. Thanks for watching!

Stateless Sessions with Spring Boot

Tue, 22 Oct 2019 00:00:00 +0000

Introduction

In the previous article, we discussed how to build a custom permissions system. In this article, we’ll discuss how to use Zuul’s reverse-proxy functionality to propagate session information in a stateless way.

Spring Session

Spring is a great framework. It has lots of built-in features and optional libraries that can be added to enable new functionality. Security and session management are two great examples of this. If you are using Spring Boot, it’s as easy as adding one of them (e.g. spring-session-core) to your classpath, and a default configuration kicks in. Further, if you add one of the extensions (like spring-session-data-redis) and an annotation (such as @EnableRedisHttpSession), you can pretty much transparently persist session state to the datastore of your choice without any other changes to your application.

Another great feature is propagating sessions. In a microservices architecture, you’ve got a lot of tiny services all doing their thing. What if you want them all to know about the currently logged-in user? I remember discussing this with a co-worker a year or so ago, when working on a new authentication system for a microservices architecture redesign of our system. It sounded theoretically possible, and solutions utilizing Spring Session or OAuth and JWTs seemed promising.

But what if there was a better way to share sessions within a microservices architecture?

Let’s build such a solution.

Set Up

Let’s define a build for our project. In this example, we’ll actually need two projects, which we’ll get to in a minute. For our first project, here’s a pom.xml skeleton to get us started:

<?xml version="1.0" encoding="utf-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.insource</groupId>
    <artifactId>custom-permissions-example</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>custom-permissions-example</name>
    <description>Example project for stateless session propagation.</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.5.RELEASE</version>
        <relativePath />
    </parent>

    <repositories>
        <repository>
            <id>spring-plugins-releases</id>
            <url>http://repo.spring.io/plugins-release</url>
        </repository>
    </repositories>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>

        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>${java.version}</source>
                        <target>${java.version}</target>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

</project>

Let’s also define an entry point for our application:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

Security Configuration

Let’s also add some security configuration to our project for example purposes. First, let’s use pre-authentication similar to what we explored in the article Stateless API Security with Spring Boot, Part 2.

import io.insource.spring.ws.examples.gateway.service.SimpleUserDetailsService;
import io.insource.spring.ws.examples.gateway.support.Http401AuthenticationEntryPoint;

import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.authentication.logout.HttpStatusReturningLogoutSuccessHandler;
import org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider;
import org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationToken;
import org.springframework.security.web.authentication.preauth.RequestHeaderAuthenticationFilter;

import java.util.Collections;

@Configuration
@EnableWebSecurity
@Order(-1)
public class
WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.antMatcher("/**")
            .addFilterAfter(preAuthenticationFilter(), RequestHeaderAuthenticationFilter.class)
            .authorizeRequests()
                .antMatchers("/api/v1/anonymous").permitAll()
                .anyRequest().authenticated()
            .and()
                .exceptionHandling().authenticationEntryPoint(authenticationEntryPoint())
            .and()
                .logout().logoutUrl("/api/v1/logout").logoutSuccessHandler(logoutSuccessHandler())
            .and()
                .csrf().disable();
    }

    public RequestHeaderAuthenticationFilter preAuthenticationFilter() {
        RequestHeaderAuthenticationFilter preAuthenticationFilter = new RequestHeaderAuthenticationFilter();
        preAuthenticationFilter.setPrincipalRequestHeader("X-USERNAME");
        preAuthenticationFilter.setAuthenticationManager(authenticationManager());
        preAuthenticationFilter.setExceptionIfHeaderMissing(false);

        return preAuthenticationFilter;
    }

    @Override
    protected AuthenticationManager authenticationManager() {
        return new ProviderManager(Collections.singletonList(authenticationProvider()));
    }

    public AuthenticationProvider authenticationProvider() {
        PreAuthenticatedAuthenticationProvider authenticationProvider = new PreAuthenticatedAuthenticationProvider();
        authenticationProvider.setPreAuthenticatedUserDetailsService(userDetailsServiceWrapper());
        authenticationProvider.setThrowExceptionWhenTokenRejected(false);

        return authenticationProvider;
    }

    public UserDetailsByNameServiceWrapper<PreAuthenticatedAuthenticationToken> userDetailsServiceWrapper() {
        return new UserDetailsByNameServiceWrapper<>(userDetailsService());
    }

    public UserDetailsService userDetailsService() {
        return new SimpleUserDetailsService();
    }

    public AuthenticationEntryPoint authenticationEntryPoint() {
        return new Http401AuthenticationEntryPoint("MyRealm");
    }

    public HttpStatusReturningLogoutSuccessHandler logoutSuccessHandler() {
        return new HttpStatusReturningLogoutSuccessHandler(HttpStatus.NO_CONTENT);
    }
}

Remember that this security configuration is just an example. Whatever authentication scheme you are using should work fine here.

Next, let’s add some authentication routes for our documentation tool to latch onto. These don’t actually perform any authentication-related tasks, as that is all handled by the Spring Security filter chain.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class LoginController {
    private static final Logger log = LoggerFactory.getLogger(LoginController.class);

    @PostMapping("/login")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void login(@RequestHeader("X-USERNAME") String username) {
        log.info("User {} successfully logged in.", username);
    }

    @PostMapping("/logout")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void logout() {
        // Just for our chosen documentation tool, not actually invoked.
    }
}

Microservice All the Things!

With the above set-up in place, let’s create a microservice to represent one of many stateless services we’ll deploy within our architecture. Each microservice will be fully session-aware and yet require no setup or overhead.

The second project is just a normal web project, so head over to Spring Initializr and select Web as a dependency to generate the project structure. Once you’ve got the second project up and running, we’ll add a controller that will eventually be able to utilize session state.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class HelloController {
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World";
    }
}

Very uninteresting, I know. But let’s make it interesting by first discussing what we plan to do with this API endpoint. The first thing to notice is that it takes no parameters. Why is this important, you ask? To answer that question, let’s examine a fundamental challenge in building APIs that are both re-usable and easy to consume.

The Proverbial Hypothetical

TL;DR; The optimal solution is not your first thought; read on to learn more.

Imagine you are building an API that manages all sorts of different things for the currently logged in user. You may need to return a list of students for a teacher and a list of tests that need to be graded, as well as submit attendance reports and manage parent-teacher topics and feedback, etc. If you plan to eventually sell this platform or host it in the cloud, but your immediate need is to deploy it on-premise at a particular school or for a particular school district, your approach might be different.

For example, in the cloud you may have a completely different authentication scheme than in the on-premise solution, or your frontend may have very different needs in each case. You may also want to eventually integrate this platform into other larger systems, or sell it as a B2B service. The list of possible problems that cause churn in your choice of how to architect session management is nearly endless. But even if you have none of the types of problems described above or any others related to it, the challenge of managing session state across a stateless architecture is definitely a daunting one.

Your first thought may be to simply find a way to propagate the session among all the disparate microservices you’ll be building. This is certainly possible, and while there are some possible ways it can be accomplished, none of them are simple, and even the artistic ones aren’t really elegant.

For example, perhaps you’ll implement an SSO using OAuth with JWTs. You’ll need an authorization server to create the tokens. Then, if you can somehow manage to have the JWTs sent to each microservice along with the request, you still have to manage shared secret keys to decode the payload, not to mention the possible size of the payload in JSON format.

Or perhaps you’ll implement clustered sessions, and propagate a JSESSIONID cookie or header instead. Each microservice will just act as if it owns the session, or at least a read-only copy of it, and load it into memory on each request, perhaps from a database or a key-value data store. This could work, though I’d love to know if anyone has a link to a good tutorial on this exact topic. Perhaps I’ll work on one, just to fully analyze the benefits and drawbacks of this approach.

At any rate, my opinion is that all of these options kind of suck. Let’s build a better solution.

The Journey

Let’s list the goals of our solution:

Make session management completely transparent to the API consumer. Keep the API documentation tool (such as Swagger) in mind - if it’s easy to use a “Try it out” button, it’ll be easy for the real API consumer.
Make the on-boarding process for new microservices in the architecture stupid simple. We want as little setup as possible. Ideally, none, at least on the microservice deployment side. We may need a bit of setup on the architectural side.
All session state we consider essential for any microservice to do its job should be available anywhere in our architecture.

With these goals in mind, the first decision point is hopefully one you’ve already made in your journey toward microservices. The question is: How do we tie all these separate deployment units together, without adding complexity on the client-side? Of course, the answer is the API Gateway pattern.

You may be tempted to say “Let’s just delegate that job to some third-party system, vendor, or platform solution, such as the PCF go-router.” While those may have a necessary place in your infrastructure, they are not going to help us here. We need our own gateway.

Add the Bits

Going back to our first project, let’s add Zuul from the Spring Cloud Netflix suite to our stack. We’ll need this to do reverse-proxy functions. If you have another routing solution in your architecture, use it. But make sure it has the additional capabilities we’ll cover shortly.

First, add the following to your pom.xml to import the Spring Cloud Maven BOM to manage Spring Cloud dependencies:

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Greenwich.SR1</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

Note: Choose the latest version of Spring Cloud, as this article may be out of date.

Then add the following dependency:

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
        </dependency>

Add a quick configuration, or add an annotation to your entrypoint application.

import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableZuulProxy
public class ZuulConfiguration {
}

Lastly, add some configuration to enable routing within Zuul:

app:
  base-url: http://localhost:8081

zuul:
  ignored-patterns:
    - /api/v1/login
    - /api/v1/logout
  routes:
    my-service:
      strip-prefix: false
      path: /api/v1/**
      url: ${app.base-url}

Note: The app.base-url property is just a stand-in for whatever downstream routing you need to do, which is outside the scope of this article. The options are numerous, but will be very tailored to your particular use case.

In our example, we’re assuming the microservice we built with an /api/v1/hello endpoint is hosted on port 8081. Here’s the relevant part of the configuration for the second project:

server:
  port: 8081

Test It Out

Now, when we log in, we can route traffic to a downstream microservice through our gateway. Using Postman (here), hit the Log In route with a POST at http://localhost:8080/api/v1/login, then issue a GET to http://localhost:8080/api/v1/hello. We’re using cookies with a JSESSIONID so make sure both requests take them into account. All the session state is managed by the gateway (currently in memory, but we can easily use Spring Session to do better).

But You Said…?

So, how do we propagate sessions? Basically all we’ve done so far is implement some authentication scheme, and a simple API gateway. Bear with me…

If we want to easily share state with these downstream microservices in a transparent way, without impacting our API contract, and without requiring any setup on the part of the downstream system, we’re left with only one choice. Let’s just use the protocol we’ve already committed to. HTTP.

Let’s use HTTP headers!

To do that, let’s add a Zuul filter to our gateway that is session-aware.

import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.User;
import org.springframework.stereotype.Component;

import static org.springframework.cloud.netflix.zuul.filters.support.FilterConstants.PRE_DECORATION_FILTER_ORDER;
import static org.springframework.cloud.netflix.zuul.filters.support.FilterConstants.PRE_TYPE;

@Component
public class ZuulSessionFilter extends ZuulFilter {
    @Override
    public String filterType() {
        return PRE_TYPE;
    }

    @Override
    public int filterOrder() {
        return PRE_DECORATION_FILTER_ORDER + 1;
    }

    @Override
    public boolean shouldFilter() {
        return true;
    }

    @Override
    public Object run() {
        doFilter();

        return null;
    }

    private void doFilter() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null) {
            // Should never happen, but could be null (see javadoc for SecurityContext#getAuthentication)
            return;
        }

        Object principal = authentication.getPrincipal();

        // Add header if user is not anonymous
        if (principal instanceof User) {
            User user = (User) principal;

            RequestContext requestContext = RequestContext.getCurrentContext();
            requestContext.addZuulRequestHeader("X-USERNAME", user.getUsername());
        }
    }
}

Again, if you’re using another gateway or reverse-proxy technology, it needs to have the capability to plug code into it that is aware of our session. Using Zuul, this is incredibly easy. We contain all the “complexity” (all 50 lines of it) in once place.

In this example, we’re not being very creative. We’ll simply be propagating the username. We could (if we’re ambitious) propagate the JSESSIONID itself. Or we could add other session attributes that we’ve previously stored with our session. The choice is up to you.

The key consideration here is to keep it light. Only information that is considered “context” or “identity” should be passed in this way. That allows each downstream microservice to have enough information to do its job, but no more. If it needs to look up the user, and that has a cost, it should be solved with additional architecture (try caching!). But passing 27KB of JSON data is not a good way to go here, nor is storing that in your session in the first place.

Ok, Ok, I know. Let’s add the final touch and look at consuming that state down stream.

The Really Tricky Bits…

Here it is. What we’ve all been waiting for.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/api/v1")
public class HelloController {
    @GetMapping("/hello")
    public String sayHello(HttpServletRequest request) {
        String username = request.getHeader("X-USERNAME");

        return String.format("Hello, %s!", username);
    }

    @GetMapping("/anonymous")
    public String sayNothing() {
        return "I have nothing to say to you. Who are you?";
    }
}

Let’s ask ourselves, have we accomplished our goals?

Make session management completely transparent to the API consumer?

Yep. We didn’t impact our API contract at all. As long as the API consumer is being routed through our gateway, they have no idea that username is a required parameter for /hello.
Make the on-boarding process for new microservices in the architecture stupid simple?

Yep. There is literally nothing special about our microservice. It’s just a regular Spring Boot app. No setup. No configuration. Nothing. Note: We did add a bit of routing to the gateway, but that’s required regardless, isn’t it?
All session state we consider essential for any microservice to do its job should be available anywhere in our architecture?

Yep. We can add any as many headers from our session as needed. We just need to keep the request size in mind. We add a tiny bit of extra information to each proxied request, and gain a huge architectural advantage.

Conclusion

In this article, we’ve learned how to build a stateful API gateway with routing using Zuul and secure it with any authentication scheme we want. We also learned how to add a Zuul request filter that adds session state to our proxied requests as HTTP headers. Finally, we learned how to set up microservices that are session-aware—in fact, we already knew how, because there’s no special setup required!

Custom Authorization with Spring Boot

Tue, 28 Aug 2018 00:00:00 +0000

Introduction

In the previous article, we discussed how to enable Restful username/password authentication. In this article, we’ll discuss how to build a custom permissions system.

Spring Security Authorization

Authorization in Spring Security is a large topic. The most common form of authorization available, one which has the most coverage in tutorials on the web, is role-based access control (RBAC). This is where you log in as a user with a particular role, say User or Admin, and are authorized to perform certain actions based on that role.

In Spring Security, the central interface for this concept is GrantedAuthority, which represents an “authority”, usually a role, such as ROLE_USER or ROLE_ADMIN. In fact, ROLE_ is so special that there are numerous aspects of Spring Security that look for it, and perform logic only when that prefix is present in the authority name. Here’s an example of a route that is protected in this way:

@RestController
public class HelloController {
    @GetMapping("/hello")
    @PreAuthorize("hasRole('ROLE_USER')")
    public String sayHello() {
        return "Hello, World";
    }
}

But what if you want to perform authorization that is more specific than something the user is granted when they log in? You might refer to this as domain object instance security. While there are numerous ways you can go deeper than role-based, you will ultimately be led to Spring Security ACL.

This extension of Spring Security forces you to adopt a specific data model for persisting your authorization data so Spring Security can perform lookups and caching of that data to enable seamless integration of ACLs into your service layer.

But what if your permissions are not traditional? I’m not sure very many existing enterprises would have their authorization concepts cleanly isolated to a few database tables that Spring Security can talk to out of the box. In those cases, you need a custom solution that’s simple to start with, and easy to extend.

Let’s build such a solution.

Set Up

Let’s define a build for our project. Here’s a pom.xml skeleton to get us started:

<?xml version="1.0" encoding="utf-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.insource</groupId>
    <artifactId>custom-permissions-example</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>custom-permissions-example</name>
    <description>Example project for method security with a custom permission evaluator.</description>

    <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>1.5.13.RELEASE</version>
            <relativePath />
        </parent>
    
        <repositories>
            <repository>
                <id>spring-plugins-releases</id>
                <url>http://repo.spring.io/plugins-release</url>
            </repository>
        </repositories>
    
        <properties>
            <java.version>1.8</java.version>
            <spring-boot.version>1.5.13.RELEASE</spring-boot.version>
        </properties>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-security</artifactId>
            </dependency>
        </dependencies>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                </plugin>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
    
            <pluginManagement>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <configuration>
                            <source>${java.version}</source>
                            <target>${java.version}</target>
                        </configuration>
                    </plugin>
                </plugins>
            </pluginManagement>
        </build>

</project>

Let’s also define an entry point for our application:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

Custom Authorization

Data Model

Let’s start with a contrived data model. This is a terrible example, but since I am not great at contriving non-incriminating examples, this will have to do. Say you have Supervisor and Employee data. Here are the models in this example:

@Entity
public class Supervisor {
    @Id
    private String name;
    @ManyToOne(mappedBy = "supervisor")
    private List<Employee> employees;
    // Constructors
    // Getters and Setters
}

@Entity
public class Employee {
    @Id
    private String name;
    private List<String> permissions = new ArrayList<>();
    @OneToMany
    private Supervisor supervisor;
    // Constructors
    // Getters and Setters
}

In this example, our permissions (the identifiers we want to use to secure our API in certain situations) are on the objects we want to secure.

Note: This may not seem like a normal example, if you're coming from the ACL model perspective, but in the real world, this is often what you get. Data coming from a system you have little/no control over (with the exception of data mapping) which has its own concept of permissions. In fact, you may normally have a situation which is even less desirable than this, where your permissions need to be derived from other data in the model, such as a status or other boolean flags. Did I mention data mapping? Hopefully, you can at least map the data coming into your application through a materialized view or a mapping layer so it looks similar to this.

Next, let’s define some way to retrieve our models. We’ll use fake Spring Data @Repository stubs for example purposes.

@Repository
public class SupervisorRepository extends JpaRepository<Supervisor, String> {
}

@Repository
public interface EmployeeRepository extends JpaRepository<Employee, String> {
    List<Employee> findBySupervisorName(String name);
}

PermissionEvaluator

The heart of Method Security (role and permissions-based authorization at the method level) in Spring Security is the PermissionEvaluator interface. For reference, it looks like this:

import java.io.Serializable;

import org.springframework.security.core.Authentication;

public interface PermissionEvaluator {
	boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission);
	boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission);
}

Out of the box, there isn’t really an implementation of this interface, other than the DenyAllPermissionEvaluator which isn’t that helpful but happens to be the default. This is why you’ll usually be steered in the direction of ACLs, which has a holistic implementation of this and other decision points within the authorization portion of the framework.

However, this interface is very easy to implement, though it is a bit archaic. In our case, we need a multi-faceted implementation to allow us to extend it very easily in the future. One way would be to take the Spring approach, and add a “manager” class, which delegates to other implementations. Let’s do that.

import org.springframework.security.access.PermissionEvaluator;
import org.springframework.security.access.expression.DenyAllPermissionEvaluator;
import org.springframework.security.core.Authentication;

import java.io.Serializable;
import java.util.Map;

public class PermissionEvaluatorManager implements PermissionEvaluator {
    private static final PermissionEvaluator denyAll = new DenyAllPermissionEvaluator();
    private final Map<String, PermissionEvaluator> permissionEvaluators;

    public PermissionEvaluatorManager(Map<String, PermissionEvaluator> permissionEvaluators) {
        this.permissionEvaluators = permissionEvaluators;
    }

    @Override
    public boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission) {
        PermissionEvaluator permissionEvaluator = permissionEvaluators.get(targetDomainObject.getClass().getSimpleName());
        if (permissionEvaluator == null) {
            permissionEvaluator = denyAll;
        }

        return permissionEvaluator.hasPermission(authentication, targetDomainObject, permission);
    }

    @Override
    public boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission) {
        PermissionEvaluator permissionEvaluator = permissionEvaluators.get(targetType);
        if (permissionEvaluator == null) {
            permissionEvaluator = denyAll;
        }

        return permissionEvaluator.hasPermission(authentication, targetId, targetType, permission);
    }
}

This manager class implements the PermissionEvaluator interface, and composes itself using two things:

A list of delegates, each matching a specific target type. This allows us to write one PermissionEvaluator for each domain object we want to support.
A default delegate. The default behavior will be to deny access if we’re asked, as that’s the framework’s fallback. This will be the DenyAllPermissionEvaluator.

If the list of delegates can’t find a match (by type name), we simply fall back denyAll.

Targeted PermissionEvaluator

Next, we need a way to target a specific type. We’ll use simple logic and only match on the type name, as mentioned above. A simple extension will suffice for this:

import org.springframework.security.access.PermissionEvaluator;

public interface TargetedPermissionEvaluator extends PermissionEvaluator {
    String getTargetType();
}

Using this interface, we can determine what type we support for each evaluator. Here’s an EmployeePermissionEvaluator:

@Component
public class EmployeePermissionEvaluator implements TargetedPermissionEvaluator {
    @Override
    public String getTargetType() {
        return Employee.class.getSimpleName();
    }

    @Override
    public boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission) {
        if (targetDomainObject != null && Employee.class.isAssignableFrom(targetDomainObject.getClass())) {
            Employee domainObject = (Employee) targetDomainObject;
            return domainObject.getPermissions().contains(permission.toString());
        }

        return false;
    }

    @Override
    public boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission) {
        throw new UnsupportedOperationException("Not supported by this PermissionEvaluator: " + EmployeePermissionEvaluator.class);
    }
}

Configure Method Security

With all that in place, we just need to configure the framework, and we can start securing APIs with Method Security and using other features of the authorization framework.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.access.PermissionEvaluator;
import org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler;
import org.springframework.security.access.expression.method.MethodSecurityExpressionHandler;
import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;
import org.springframework.security.config.annotation.method.configuration.GlobalMethodSecurityConfiguration;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class MethodSecurityConfiguration extends GlobalMethodSecurityConfiguration {
    private final List<TargetedPermissionEvaluator> permissionEvaluators;

    @Autowired
    public MethodSecurityConfiguration(List<TargetedPermissionEvaluator> permissionEvaluators) {
        this.permissionEvaluators = permissionEvaluators;
    }

    @Override
    protected MethodSecurityExpressionHandler createExpressionHandler() {
        DefaultMethodSecurityExpressionHandler methodSecurityExpressionHandler = new DefaultMethodSecurityExpressionHandler();
        methodSecurityExpressionHandler.setPermissionEvaluator(permissionEvaluator());

        return methodSecurityExpressionHandler;
    }

    @Bean
    public PermissionEvaluator permissionEvaluator() {
        Map<String, PermissionEvaluator> map = new HashMap<>();

        // Build lookup table of PermissionEvaluator by supported target type
        for (TargetedPermissionEvaluator permissionEvaluator : permissionEvaluators) {
            map.put(permissionEvaluator.getTargetType(), permissionEvaluator);
        }

        return new PermissionEvaluatorManager(map);
    }
}

Let’s break this down.

Enable Method Security. We also extend GlobalMethodSecurityConfiguration to override what we need to.
Autowire the list of TargetedPermissionEvaluators found in the ApplicationContext.
Set up the PermissionEvaluatorManager by building a lookup table of PermissionEvaluator delegates.
Wire that up to the DefaultMethodSecurityExpressionHandler to be used by our @Pre and @Post method security.

Note: We can't simply component-scan the PermissionEvaluatorManager because we have numerous of PermissionEvaluators on the classpath. The technique above ensures only the one we want is used. There are a few hacky ways to do this, but the above is the cleanest way to ensure our intended manager class is used.

Secure your API

With the security layer configured, we can now use @Pre and @Post annotations to secure our API. Instead of the traditional placement of these annotations on the service layer, let’s place them on our API directly. It’s your choice, but putting them in controllers makes the authorization easier to document and understand, and makes your service layer more reusable (by choosing when to lock it down, and when not to).

import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PostFilter;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

import javax.inject.Inject;
import java.util.List;
import java.util.Map;

@RestController
public class EmployeeController {
    @Inject
    private EmployeeRepository employeeRepository;

    @GetMapping("/supervisors/{name}/employees")
    public List<Employee> getEmployees(@PathVariable("name") String supervisorName) {
        return employeeRepository.findBySupervisorName(supervisorName);
    }

    @PostFilter("hasPermission(filterObject, #permission + '.' + #ext)")
    @GetMapping("/supervisors/{name}/employees/{permission}.{ext}")
    public List<Employee> getEmployeesWithPermission(@PathVariable("name") String name, @PathVariable("permission") String permission, @PathVariable("ext") String ext) {
        return employeeRepository.findBySupervisorName(name);
    }

    @PreAuthorize("hasPermission(#report['name'], 'Employee', 'expenseReport.allowed')")
    @PostMapping("/employees/expense-report")
    @ResponseStatus(HttpStatus.ACCEPTED)
    public void submitExpenseReport(@RequestBody Map<String, String> report) {
        // Do something with expense report data...
    }
}

In this example, we are using Method Security for two of our three routes.

getEmployees(): No authorization. Just list employees by supervisor.
getEmployeesWithPermission(): Uses a post-filter. This demonstrates reusing an existing query, but filtering the list based on permissions in our data model. Not applicable in all cases (for performance reasons), but useful for keeping LoC low and reusing queries with authorization logic for filtering.
submitExpenseReport(): Uses a pre-authorize check. Ensures the employee has expense-report permission and the current user (not necessarily that employee) should be allowed to submit an expense report for that employee.

Again, these are contrived examples. But the important thing to note is how we’ve hooked into Spring Security to perform pre/post authorize or filtering logic with a very custom permissions scheme. You should note that with access to the Authentication in the PermissionEvaluator, you can make these checks specific to the currently logged in user, or not. It all depends on your requirements. I’ll leave these custom implementations up to you. Happy coding!

Conclusion

In this article, we’ve learned how to create an extensible permissions evaluation scheme with custom permission data in our model. We also learned how we can use that scheme to perform pre/post authorization logic, including filtering.

Innocuous Code Lurks Around Every Corner

Mon, 27 Aug 2018 00:00:00 +0000

After about three hours of debugging Spring Framework code to make a simple OAuth2 authenticated call to Reddit, I finally have some semblance of understanding around why my life sucks right now. I am not insane.

TLDR;

Perhaps in another post, we’ll discuss how to actually connect to Reddit’s API via Java (or Kotlin) code and do something useful. But I can at least explain why it doesn’t work. Let’s dig in.

The Setup

In order to connect to any OAuth-based server from a Spring project, you need a bit of configuration. Plenty of examples on the web, so not treading new ground here. But for completeness, here’s what we’re dealing with. The following is the important snippet of my build:

build.gradle

dependencies {
    compile('org.springframework:spring-web')
    compile('org.springframework.security.oauth:spring-security-oauth2')
}

I’m using the client_credentials grant type for simplicity, but will eventually switch to authorization_code.

There's a pretty decent tutorial on this topic over at Baeldung.

Here’s a simple configuration using @Value properties from a @PropertySource pointing to reddit.properties in src/main/resources.

RedditOAuthConfiguration.kt

package com.reddit

import org.springframework.beans.factory.annotation.Value
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.PropertySource
import org.springframework.security.oauth2.client.OAuth2ClientContext
import org.springframework.security.oauth2.client.OAuth2RestTemplate
import org.springframework.security.oauth2.client.token.grant.client.ClientCredentialsAccessTokenProvider
import org.springframework.security.oauth2.client.token.grant.client.ClientCredentialsResourceDetails
import org.springframework.security.oauth2.config.annotation.web.configuration.EnableOAuth2Client

@Configuration
@EnableOAuth2Client
@PropertySource("classpath:reddit.properties")
class RedditOAuthConfiguration(
  @Value("\${clientId}")
  private val clientId: String,

  @Value("\${clientSecret}")
  private val clientSecret: String,

  @Value("\${accessTokenUri}")
  private val accessTokenUri: String
) {
  @Bean
  fun reddit() = ClientCredentialsResourceDetails().also {
    it.id = "reddit"
    it.clientId = clientId
    it.clientSecret = clientSecret
    it.scope = arrayListOf("identity")
    it.accessTokenUri = accessTokenUri
  }

  @Bean
  fun redditRestTemplate(clientContext: OAuth2ClientContext) = OAuth2RestTemplate(reddit(), clientContext).also {
    it.setAccessTokenProvider(ClientCredentialsAccessTokenProvider())
  }
}

With that configuration defining a RestTemplate and enabling a Oauth2ClientContextFilter (via @EnableOAuth2Client), we can use it. In my case, I’m stuffing it into a Swagger-generated API client.

RedditApiConfiguration.kt

package com.reddit

import com.reddit.api.RedditApi
import org.springframework.beans.factory.annotation.Value
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.PropertySource
import org.springframework.security.oauth2.client.OAuth2RestTemplate

@Configuration
@PropertySource("classpath:reddit.properties")
class RedditApiConfiguration(
  @Value("\${basePath}")
  private val basePath: String
) {
  @Bean
  fun redditApi(oAuth2RestTemplate: OAuth2RestTemplate) =
    RedditApi(ApiClient(oAuth2RestTemplate).also {
      it.basePath = basePath
    })
}

Here’s an example of reddit.properties. The userAuthorizationUri is there if you want to switch grant types.

reddit.properties

clientId=...
clientSecret=...
#userAuthorizationUri=https://www.reddit.com/api/v1/authorize
accessTokenUri=https://www.reddit.com/api/v1/access_token
basePath=https://oauth.reddit.com

The Problem

So with this in place, any attempt to use the API client (and by association, the RestTemplate) to talk to Reddit’s API results in this:

org.springframework.security.oauth2.common.exceptions.OAuth2Exception: 429
	at org.springframework.security.oauth2.common.exceptions.OAuth2ExceptionJackson2Deserializer.deserialize(OAuth2ExceptionJackson2Deserializer.java:120) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.security.oauth2.common.exceptions.OAuth2ExceptionJackson2Deserializer.deserialize(OAuth2ExceptionJackson2Deserializer.java:1) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at com.fasterxml.jackson.databind.ObjectMapper._readMapAndClose(ObjectMapper.java:4013) ~[jackson-databind-2.9.6.jar:2.9.6]
	at com.fasterxml.jackson.databind.ObjectMapper.readValue(ObjectMapper.java:3084) ~[jackson-databind-2.9.6.jar:2.9.6]
	at org.springframework.http.converter.json.AbstractJackson2HttpMessageConverter.readJavaType(AbstractJackson2HttpMessageConverter.java:237) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.http.converter.json.AbstractJackson2HttpMessageConverter.readInternal(AbstractJackson2HttpMessageConverter.java:217) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.http.converter.AbstractHttpMessageConverter.read(AbstractHttpMessageConverter.java:198) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.security.oauth2.client.token.OAuth2AccessTokenSupport$AccessTokenErrorHandler.handleError(OAuth2AccessTokenSupport.java:235) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.web.client.ResponseErrorHandler.handleError(ResponseErrorHandler.java:63) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.web.client.RestTemplate.handleResponse(RestTemplate.java:766) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:724) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.web.client.RestTemplate.execute(RestTemplate.java:690) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.security.oauth2.client.token.OAuth2AccessTokenSupport.retrieveToken(OAuth2AccessTokenSupport.java:137) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.security.oauth2.client.token.grant.client.ClientCredentialsAccessTokenProvider.obtainAccessToken(ClientCredentialsAccessTokenProvider.java:44) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.security.oauth2.client.OAuth2RestTemplate.acquireAccessToken(OAuth2RestTemplate.java:221) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.security.oauth2.client.OAuth2RestTemplate.getAccessToken(OAuth2RestTemplate.java:173) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.security.oauth2.client.OAuth2RestTemplate.createRequest(OAuth2RestTemplate.java:105) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:719) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at org.springframework.security.oauth2.client.OAuth2RestTemplate.doExecute(OAuth2RestTemplate.java:128) ~[spring-security-oauth2-2.0.6.RELEASE.jar:na]
	at org.springframework.web.client.RestTemplate.exchange(RestTemplate.java:668) ~[spring-web-5.0.8.RELEASE.jar:5.0.8.RELEASE]
	at com.reddit.ApiClient.invokeAPI(ApiClient.java:530) ~[classes/:na]
	at com.reddit.api.RedditApi.meUsingGET(RedditApi.java:78) ~[classes/:na]
    ...

Not very helpful. Spending lots of time tracing code yields a request reproduced via Postman that looks like this (using cURL):

curl -X POST \
  https://www.reddit.com/api/v1/access_token \
  -H 'Accept: application/json, application/x-www-form-urlencoded' \
  -H 'Authorization: Basic XDlvLWJJS0VTd1RzTEE6cm9mWG5Db1V4OHJTaj2W8UtGcx9QSUVmW2Lr' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Length: 44' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=identity'

Amazingly, this works perfectly and produces the following:

{
    "access_token": "-6808zn3KtBjkWJ7b7Z-lpmyKp_4",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "identity"
}

So if I can hit this with Postman just fine, but not Java, what gives? So I traced the code some more, until I could fine every applicable line of code that results in making the actual API call to get the token. Here’s the reproduced scenario in a unit test:

HttpTest.kt

package io.insource.api.demo

import org.hamcrest.Matchers.`is`
import org.junit.Assert.assertThat
import org.junit.Test
import org.springframework.http.HttpStatus
import org.springframework.http.MediaType
import org.springframework.util.FileCopyUtils
import java.net.HttpURLConnection
import java.net.URL
import java.nio.charset.StandardCharsets

class HttpTest {
  @Test fun testHttpURLConnection() {
    val charset = MediaType(MediaType.APPLICATION_FORM_URLENCODED, StandardCharsets.UTF_8).charset!!
    val bytes = "grant_type=client_credentials&scope=identity".toByteArray(charset)

    val url = URL("https://www.reddit.com/api/v1/access_token")
    val connection = url.openConnection() as HttpURLConnection
    connection.connectTimeout = 30000
    connection.readTimeout = 30000
    connection.doInput = true
    connection.doOutput = true
    connection.instanceFollowRedirects = false
    connection.requestMethod = "POST"
    connection.addRequestProperty("Authorization", "Basic XDlvLWJJS0VTd1RzTEE6cm9mWG5Db1V4OHJTaj2W8UtGcx9QSUVmW2Lr")
    connection.addRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8")
    connection.addRequestProperty("Accept", "application/json, application/x-www-form-urlencoded")
    connection.addRequestProperty("Content-Length", bytes.size.toString())
    connection.connect()
    FileCopyUtils.copy(bytes, connection.outputStream)

    val httpStatus = HttpStatus.resolve(connection.responseCode)
    assertThat(httpStatus, `is`(HttpStatus.OK))

    val responseBody = FileCopyUtils.copyToByteArray(connection.inputStream).toString()
    println(responseBody)
  }
}

So now we ask ourselves, “What do we know?”

“Well, we know that we keep getting errors. We also know that it works fine in a sane HTTP client, like Postman or cURL. So we know Java is being weird. But why…”

Then I looked closer. Let’s ask ourselves again, “What do we know?”

“Well, we know we get a 429 error. Wait… 429? That’s some !@#$ ain’t it? Why is it giving us 429 Too Many Requests? Reddit’s API is dropping us, isn’t it? Hmm….”

Yep, it’s confirmed. There’s rate limiting going on. But if we’re not DDoS’ing Reddit’s API, who is? Well, as it turns out, everyone is. The rate limit is high enough for most API consumers to get by fine, but if you combine it with all the people making the same uneducated requests to Reddit’s API that I am, you get quite a lot of noise. The answer, as it turns out, is here:

Reddit Wiki - API

Change your client’s User-Agent string to something unique and descriptive, including the target platform, a unique application identifier, a version string, and your username as contact information, in the following format:

<platform>:<app ID>:<version string> (by /u/)

Example: User-Agent: android:com.example.myredditapp:v1.2.3 (by /u/kemitche)

Many default User-Agents (like “Python/urllib” or “Java”) are drastically limited to encourage unique and descriptive user-agent strings.

If we add a User-Agent header (anything unique-ish basically), the minimal test case passes and prints our response.

package io.insource.api.demo

import org.hamcrest.Matchers.`is`
import org.junit.Assert.assertThat
import org.junit.Test
import org.springframework.http.HttpStatus
import org.springframework.http.MediaType
import org.springframework.util.FileCopyUtils
import java.net.HttpURLConnection
import java.net.URL
import java.nio.charset.StandardCharsets

class HttpTest {
  @Test fun testHttpURLConnection() {
    val charset = MediaType(MediaType.APPLICATION_FORM_URLENCODED, StandardCharsets.UTF_8).charset!!
    val bytes = "grant_type=client_credentials&scope=identity".toByteArray(charset)

    val url = URL("https://www.reddit.com/api/v1/access_token")
    val connection = url.openConnection() as HttpURLConnection
    connection.connectTimeout = 30000
    connection.readTimeout = 30000
    connection.doInput = true
    connection.doOutput = true
    connection.instanceFollowRedirects = false
    connection.requestMethod = "POST"
    connection.addRequestProperty("Authorization", "Basic XDlvLWJJS0VTd1RzTEE6cm9mWG5Db1V4OHJTaj2W8UtGcx9QSUVmW2Lr")
    connection.addRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8")
    connection.addRequestProperty("Accept", "application/json, application/x-www-form-urlencoded")
    it.addRequestProperty("User-Agent", "This is a test")
    connection.addRequestProperty("Content-Length", bytes.size.toString())
    connection.connect()
    FileCopyUtils.copy(bytes, connection.outputStream)

    val httpStatus = HttpStatus.resolve(connection.responseCode)
    assertThat(httpStatus, `is`(HttpStatus.OK))

    val responseBody = FileCopyUtils.copyToByteArray(connection.inputStream).toString()
    println(responseBody)
  }
}

So why did cURL and Postman work? As it turns out, cURL works only sometimes. And postman must be silently adding a User-Agent header and not telling us. Either that, or it’s not nearly as limited as the Java User-Agent (which is either null or another silent thing being added to requests that don’t have a User-Agent, I’m unsure which).

So after all that, the answer is don’t skimp reading the documentation. Especially if it’s poorly organized and not cohesive or in one place like it should be.

Custom Authentication with Spring Boot

Wed, 06 Jun 2018 00:00:00 +0000

Introduction

In the previous article, we discussed adding an Authorization header and a custom security scheme to a Spring Boot application for stateless API security. In this article, we’ll discuss how to enable Restful username/password authentication.

Rest Authentication

In Spring Security, it’s been fairly effortless to enable username/password authentication through Form Login, which is a vestige of a bygone era of simple login screens and stateful servers before single page applications were prevalent (or even existed). Admittedly, once an HTTP POST with URL encoded form data is no longer viable, it’s likely that username/password authentication is not viable either. Most likely, we’ll want a multi-factor authentication flow. We’ll discuss this in a future post.

For now, let’s look at how to bypass the traditional form login, but use the same concepts with a JSON-based API.

Set Up

Let’s define a build for our project. Here’s a pom.xml skeleton to get us started:

<?xml version="1.0" encoding="utf-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.insource</groupId>
    <artifactId>customauth-security-example</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>customauth-security-example</name>
    <description>Example project for securing REST endpoints with custom authentication.</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.13.RELEASE</version>
        <relativePath />
    </parent>

    <repositories>
        <repository>
            <id>spring-plugins-releases</id>
            <url>http://repo.spring.io/plugins-release</url>
        </repository>
    </repositories>

    <properties>
        <java.version>1.8</java.version>
        <spring-boot.version>1.5.13.RELEASE</spring-boot.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>

        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>${java.version}</source>
                        <target>${java.version}</target>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

</project>

Let’s also define an entry point for our application:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

Lastly, let’s define an endpoint we want to be able to secure:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class HelloController {
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World";
    }
}

Custom Auth Filter

Instead of using the traditional formLogin() configurer, let’s author our own simple filter. In fact, we can extend the existing form login filter, called UsernamePasswordAuthenticationFilter, and provide a tiny bit of code to get access to a request body.

Create the following class:

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.HashMap;

public class CustomAuthenticationFilter extends UsernamePasswordAuthenticationFilter {
	private static final String BODY_ATTRIBUTE = CustomAuthenticationFilter.class.getSimpleName() + ".body";

	private final ObjectMapper objectMapper;

	public CustomAuthenticationFilter(ObjectMapper objectMapper) {
		this.objectMapper = objectMapper;
	}

	@Override
	public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {
		HttpServletRequest request = (HttpServletRequest) req;
		HttpServletResponse response = (HttpServletResponse) res;

		// Parse the request body as a HashMap and populate a request attribute
		if (requiresAuthentication(request, response)) {
			UsernamePasswordRequest usernamePasswordRequest = objectMapper.readValue(request.getInputStream(), UsernamePasswordRequest.class);
			request.setAttribute(BODY_ATTRIBUTE, usernamePasswordRequest);
		}

		super.doFilter(req, res, chain);
	}

	protected String obtainUsername(HttpServletRequest request) {
		UsernamePasswordRequest usernamePasswordRequest = (UsernamePasswordRequest) request.getAttribute(BODY_ATTRIBUTE);
		return usernamePasswordRequest.get(getUsernameParameter());
	}

	protected String obtainPassword(HttpServletRequest request) {
		UsernamePasswordRequest usernamePasswordRequest = (UsernamePasswordRequest) request.getAttribute(BODY_ATTRIBUTE);
		return usernamePasswordRequest.get(getPasswordParameter());
	}

	private static class UsernamePasswordRequest extends HashMap<String, String> {
		// Nothing, just a type marker
	}
}

This class makes use of everything provided by UsernamePasswordAuthenticationFilter which in turn extends AbstractAuthenticationProcessingFilter. It will terminate processing of the request if it finds a request that matches, so no @RestController will be invoked (just as with Form Login).

In addition to the UsernamePasswordAuthenticationToken and other window dressing that is created by the parent class, we take over processing the request body. Using a simple ObjectMapper, we can convert an arbitrary key/value JSON structure into a HashMap.

Once the body is parsed, we can easily obtain an arbitrarily named username and password, just as with Form Login. We use a bit of request attribute trickery just to satisfy the method calls made by the parent class.

Customize Authentication

Once we have a basic custom filter in place to do authentication (note we didn’t have to code that part), let’s turn our attention to configuring Spring Security.

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.boot.autoconfigure.security.Http401AuthenticationEntryPoint;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;
import org.springframework.security.web.authentication.SimpleUrlAuthenticationSuccessHandler;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.security.web.authentication.preauth.RequestHeaderAuthenticationFilter;
import org.springframework.security.web.authentication.session.ChangeSessionIdAuthenticationStrategy;
import org.springframework.security.web.authentication.session.CompositeSessionAuthenticationStrategy;
import org.springframework.security.web.authentication.session.SessionAuthenticationStrategy;
import org.springframework.security.web.csrf.CsrfAuthenticationStrategy;
import org.springframework.security.web.csrf.CsrfTokenRepository;
import org.springframework.security.web.csrf.HttpSessionCsrfTokenRepository;
import org.springframework.security.web.csrf.LazyCsrfTokenRepository;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;

import java.util.Arrays;

@Configuration
@EnableWebSecurity
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.antMatcher("/**")
            .addFilterAfter(customAuthFilter(), RequestHeaderAuthenticationFilter.class)
            .authorizeRequests()
                .antMatchers("/login", "/csrf").permitAll()
                .anyRequest().authenticated()
            .and()
                .csrf().csrfTokenRepository(csrfTokenRepository())
            .and()
                .exceptionHandling().authenticationEntryPoint(authenticationEntryPoint())
            .and()
                .formLogin().disable();
    }

    @Bean
    public UsernamePasswordAuthenticationFilter customAuthFilter() throws Exception {
        UsernamePasswordAuthenticationFilter authenticationFilter = new CustomAuthenticationFilter(objectMapper());
        authenticationFilter.setRequiresAuthenticationRequestMatcher(new AntPathRequestMatcher("/login", "POST"));
        authenticationFilter.setUsernameParameter("username");
        authenticationFilter.setPasswordParameter("password");
        authenticationFilter.setAuthenticationManager(authenticationManagerBean());
        authenticationFilter.setAuthenticationSuccessHandler(authenticationSuccessHandler());
        authenticationFilter.setSessionAuthenticationStrategy(sessionAuthenticationStrategy());

        return authenticationFilter;
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.inMemoryAuthentication()
            .withUser("user").password("password").roles("USER").and()
            .withUser("admin").password("admin").roles("ADMIN");
    }

    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }

    @Bean
    public AuthenticationSuccessHandler authenticationSuccessHandler() {
        return new SimpleUrlAuthenticationSuccessHandler("/");
    }

    @Bean
    public SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new CompositeSessionAuthenticationStrategy(Arrays.asList(
            new ChangeSessionIdAuthenticationStrategy(),
            new CsrfAuthenticationStrategy(csrfTokenRepository())
        ));
    }

    @Bean
    public CsrfTokenRepository csrfTokenRepository() {
        return new LazyCsrfTokenRepository(new HttpSessionCsrfTokenRepository());
    }

    @Bean
    public AuthenticationEntryPoint authenticationEntryPoint() {
        return new Http401AuthenticationEntryPoint("MyRealm");
    }

    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper();
    }
}

There’s a few things going on here, so let’s break it down.

Configuration

First, we wire in our custom extension of UsernamePasswordAuthenticationFilter. It’s best to define an order for the filter to fit into the filter chain. In this case, it doesn’t clash with anything in the defaults, so we could skip this step, but in case we add pre-auth (see previous tutorials), the addFilterAfter() ensures it will be after that filter if present. In this case, it fires pretty early in the chain.

Next, we manually open up the /login and /csrf routes and lock down everything else.

We also need to make sure our CSRF protection is consistent between the default filter chain and our custom filter, so we need to define the glue piece manually, which is the HttpSessionCsrfTokenRepository. We use this later as well.

Then we disable the default form login, which would put another UsernamePasswordAuthenticationFilter into the filter chain and we definitely don’t want that.

UsernamePasswordAuthenticationFilter

In order to configure our filter, we need several additional things.

First, we define an ObjectMapper to use with our custom JSON parsing inside the filter.

Then, we define the request matcher. We don’t have helper methods for this custom filter but it’s not hard to do it manually with an AntPathRequestMatcher. This makes it identical to the default form login configuration, but with JSON instead of form fields.

Also similar to the defaults, we set up the username and password fields that will hold our principal and credentials. I’ve explicitly set them to call out where to configure them for your needs.

We then define a SessionAuthenticationStrategy, since we don’t get any defaults for free. I haven’t ensured this is perfectly consistent with the defaults, so comments are welcome, but in this example, we’re also adding session-fixation and CSRF protection to the filter chain with a CompositeSessionAuthenticationStrategy. The CsrfAuthenticationStrategy uses the same CsrfTokenRepository we defined above, which also gets used by our own custom controller (shown below) to expose the CSRF token.

We also define an AuthenticationEntryPoint to throw a 401 Unauthorized with a WWW-Authenticate response header containing our custom realm name when unauthenticated API calls are made.

Update: If you are using Spring Boot 2.x, please note that the Http401AuthenticationEntryPoint class has been removed. For reference, view this file on GitHub if you need to copy it and define it within your project.

Lastly, we define a simple AuthenticationManager and AuthenticationSuccessHandler. The important thing about the AuthenticationManager is we need to expose it as a bean so we can add it to our custom filter.

Note: This is also useful if we need to access it from somewhere within our application, as the default security configurer does not expose any of these objects as beans. You may need that, for example, if you want to build a password management screen where you need to re-test the user's credentials prior to changing them.

Expose the CSRF

We need to add one piece that’s missing from the form generated by the DefaultLoginPageGeneratingFilter. I’ve not seen any tutorials for how to do this, but the docs cover this deep into the weeds of Spring Security. We can use the CsrfTokenArgumentResolver to get a handle on the CsrfToken automatically.

Let’s add a @RestController to our application:

import org.springframework.http.HttpStatus;
import org.springframework.security.web.csrf.CsrfToken;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AuthController {
    @GetMapping("/")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void getIndex() {
    }

    @GetMapping("/login")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void getLogin() {
    }

    @GetMapping("/csrf")
    public CsrfToken getCsrf(CsrfToken csrfToken) {
        return csrfToken;
    }
}

The GET / and GET /login routes are optional, but creates a simple landing page that tells you that you’ve logged in and out successfully.

The GET /csrf route replaces the _csrf hidden attribute from the Form Login page by utilizing the aforementioned CsrfTokenRepository through the CsrfTokenArgumentResolver. API consumers will need to obtain the CSRF prior to invoking the /login route, as the entire application has CSRF protection enabled. Invoking it produces the following output:

{
    "token": "2f1f8b7f-660f-4285-8a08-b29c789c8f60",
    "headerName": "X-CSRF-TOKEN",
    "parameterName": "_csrf"
}

Here is a sample CURL request for using the CSRF token:

curl -X POST \
  http://localhost:8080/login \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-CSRF-TOKEN: 2f1f8b7f-660f-4285-8a08-b29c789c8f60' \
  -d '{
	"username": "user",
	"password": "password"
  }'

X-CSRF-TOKEN is the default name of the header required by the CsrfFilter that was enabled with csrf() in our WebSecurityConfigurerAdapter.

Conclusion

In this article, we’ve learned how to create a custom username/password authentication filter, and manually configure Spring Security to use it. We also learned how to expose the CSRF token through our REST API with consistent CSRF protection throughout the application.

Stateless API Security with Spring Boot, Part 2

Thu, 31 May 2018 00:00:00 +0000

Introduction

In the previous article, we discussed adding Basic authentication to our project and turned off session management for a pure stateless API. In this article, we’ll discuss how to extend that using an Authorization header and a custom security scheme.

Custom Authentication Scheme

Let’s now turn our attention to how to evolve beyond the Basic authentication scheme, which has limited uses for us in practice (though it can be a very suitable model for simple app-to-app security). Let’s imagine that we want to provision API keys for clients to consume our API. With the previous concepts in place, we have the ability to do username/password authentication. But we need to move to a new scheme that only uses tokens as credentials.

Add Pre-Authentication

Instead of basic auth, let’s define a customized filter to enable pre-authentication. You may have seen tutorials on the web using the SM_USER header to do this. This is Siteminder security, which assumes an API Gateway is forcing users to authenticate prior to hitting our application, and providing a header with the pre-authenticated username.

Let’s use this concept with the Authorization header. Replace the Java config we defined for Basic auth with the following:

import org.springframework.boot.autoconfigure.security.Http401AuthenticationEntryPoint;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.concurrent.ConcurrentMapCache;
import org.springframework.cache.support.SimpleCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.userdetails.AuthenticationUserDetailsService;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider;
import org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationToken;
import org.springframework.security.web.authentication.preauth.RequestHeaderAuthenticationFilter;

import java.util.Collections;
import java.util.regex.Pattern;

@Configuration
@EnableWebSecurity
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    public static final String REALM_NAME = "MyRealm";
    public static final String API_KEY_PARAM = "apikey";
    public static final Pattern AUTHORIZATION_HEADER_PATTERN = Pattern.compile(
        String.format("%s %s=\"(\\S+)\"", REALM_NAME, API_KEY_PARAM)
    );

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.antMatcher("/**")
            .addFilterAfter(preAuthenticationFilter(), RequestHeaderAuthenticationFilter.class)
            .authorizeRequests()
                .anyRequest().authenticated()
            .and()
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
                .exceptionHandling().authenticationEntryPoint(authenticationEntryPoint())
            .and()
                .csrf().disable();
    }

    @Bean
    public RequestHeaderAuthenticationFilter preAuthenticationFilter() {
        RequestHeaderAuthenticationFilter preAuthenticationFilter = new RequestHeaderAuthenticationFilter();
        preAuthenticationFilter.setPrincipalRequestHeader("Authorization");
        preAuthenticationFilter.setCredentialsRequestHeader("Authorization");
        preAuthenticationFilter.setAuthenticationManager(authenticationManager());
        preAuthenticationFilter.setExceptionIfHeaderMissing(false);

        return preAuthenticationFilter;
    }

    @Override
    protected AuthenticationManager authenticationManager() {
        return new ProviderManager(Collections.singletonList(authenticationProvider()));
    }

    @Bean
    public AuthenticationProvider authenticationProvider() {
        PreAuthenticatedAuthenticationProvider authenticationProvider = new PreAuthenticatedAuthenticationProvider();
        authenticationProvider.setPreAuthenticatedUserDetailsService(userDetailsServiceWrapper());
        authenticationProvider.setThrowExceptionWhenTokenRejected(false);

        return authenticationProvider;
    }

    @Bean
    public AuthenticationUserDetailsService<PreAuthenticatedAuthenticationToken> userDetailsServiceWrapper() {
        return new AuthorizationUserDetailsService();
    }

    @Bean
    public AuthenticationEntryPoint authenticationEntryPoint() {
        return new Http401AuthenticationEntryPoint(REALM_NAME);
    }
}

This is a larger configuration. Let’s break it down.

Constants

We’ve defined some constants at the top of the file. We could use a similar @ConfigurationProperties technique as before. But by the time we’re defining our own security model, it’s probably overkill to make it configurable. Using the RFC 2617 format, we’ve defined a custom scheme. It looks like this:

Authorization: MyRealm apikey="..."

PreAuthenticationFilter

We’ve defined a filter using a stock Spring class, RequestHeaderAuthenticationFilter. As with the Siteminder example, we can take any header we like and use it to perform “pre” authentication.

What this does is assume that the authentication was performed elsewhere, and our job is to validate or simply use the header to create an authenticated session. In this example, we’ve turned off session management (we’ll see why that’s important in a minute), so we’re actually just creating a SecurityContext on each API call. That sounds expensive. We’ll fix it later.

With this filter, we have to define a bunch of pieces to make it work.

1. We’ve provided an instance of RequestHeaderAuthenticationFilter.

We’ve configured it with a principal (required) and credentials (optional) and told it not to puke on missing header (so our authentication entrypoint is used instead).

2. We’ve provided an AuthenticationManager with a single AuthenticationProvider.

Our provider of type PreAuthenticatedAuthenticationProvider expects an AuthenticationUserDetailsService parameterized with PreAuthenticatedAuthenticationToken.

3. We’ve provided a AuthenticationUserDetailsService to do the creation of a UserDetails.

This is where our custom authorization logic will go, based on the PreAuthenticatedAuthenticationToken given by our provider.

AuthenticationEntryPoint

Our entry point simply throws a 401 Unauthorized with a WWW-Authenticate response header containing our custom auth scheme when things go wrong or are missing.

UserDetailsService

There’s some magic in the AuthenticationUserDetailsService, so let’s explore that. Here’s the definition:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;

import java.util.Collections;
import java.util.regex.Matcher;

/* Not marked @Component to simplify WebSecurityConfiguration. */
public class AuthorizationUserDetailsService implements AuthenticationUserDetailsService<PreAuthenticatedAuthenticationToken> {
    private static final Logger logger = LoggerFactory.getLogger(AuthorizationUserDetailsService.class);

    @Override
    public UserDetails loadUserDetails(PreAuthenticatedAuthenticationToken token) throws UsernameNotFoundException {
        String authorizationHeader = token.getCredentials().toString();
        logger.info("Loading user for Authorization header: " + authorizationHeader);

        // Check authentication scheme
        if (!authorizationHeader.startsWith(WebSecurityConfiguration.REALM_NAME)) {
            throw new AuthorizationHeaderException("Invalid authentication scheme found in Authorization header");
        }

        // Check for apikey parameter
        if (!authorizationHeader.contains(WebSecurityConfiguration.API_KEY_PARAM)) {
            throw new AuthorizationHeaderException("Unable to locate apikey parameter in Authorization header");
        }

        // Check that the Authorization header matches the pattern
        Matcher matcher = WebSecurityConfiguration.AUTHORIZATION_HEADER_PATTERN.matcher(authorizationHeader);
        if (!matcher.matches()) {
            throw new AuthorizationHeaderException("Unable to parse apikey from Authorization header");
        }

        return loadUserDetails(matcher.group());
    }

    private UserDetails loadUserDetails(String apiKey) {
        // TODO: Implement with your own logic to resolve API key (from Authentication header value)
        return new User("user", apiKey, Collections.singletonList(new SimpleGrantedAuthority("ROLE_USER")));
    }
}

This is the easiest place I can think of to place our custom auth scheme logic. The AuthenticationUserDetailsService is usually used to convert a principal/credentials pair into a UserDetails. But we can easily use it to do some validation first. The Authorization header value is passed in the PreAuthenticatedAuthenticationToken, so we can use that to convert to a user however we wish to.

First, we validate that the header value is in the right format. Marginally expensive, but negligible in the scheme of things.

Then we parse the apiKey from the header. Once we have this, we’re in the driver’s seat as to how we implement the lookup/conversion. You can look up the user in an API key provisioning database or load them from a JWT. You can also place roles or other information in this User object, or define your own custom UserDetails implementation.

What’s missing from this example is what happens if the apiKey is invalid. Just throw an exception similar to the above validation logic. By the way, here’s that exception:

import org.springframework.http.HttpStatus;
import org.springframework.security.core.AuthenticationException;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(HttpStatus.UNAUTHORIZED)
public class AuthorizationHeaderException extends AuthenticationException {
    public AuthorizationHeaderException(String msg) {
        super(msg);
    }

    public AuthorizationHeaderException(String msg, Throwable t) {
        super(msg, t);
    }
}

You can also use the UsernameNotFoundException from the method signature if you prefer.

Stateless???

The last problem with this scheme is that we’re attempting to be stateless. Without sessions, we’re kind of hosed from a performance perspective. Now, if you wish to enable sessions for your use case, you’re welcome to. And there are many good reasons to do it. But in this case, we’re developing a pure API that is consumed by another process or API consumer, not a web browser.

All “stateless” means in this context is that there shouldn’t be any state stored in our JVM. Of course, for example purposes we’re going to do that, but in production, you’ll want to bind in sidecar services to handle it, such as Redis or MongoDB. Those would also be good choices if you want to re-enable sessions.

But in this case, we’re going to practice treating stateless (part of any good 12 factor app) the right way, and make it totally transparent. Simply add this bean definition to the Java config above:

import io.insource.spring.ws.examples.security.service.AuthorizationUserDetailsService;

import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.concurrent.ConcurrentMapCache;
import org.springframework.cache.support.SimpleCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

import java.util.Collections;

@Configuration
@EnableWebSecurity
@EnableCaching
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    ...

    @Bean
    public CacheManager cacheManager() {
        SimpleCacheManager cacheManager = new SimpleCacheManager();
        cacheManager.setCaches(Collections.singletonList(new ConcurrentMapCache("users")));

        return cacheManager;
    }
}

With that in place (replace with your chosen production sidecar for caching, outside the scope of this article), we can start caching stuff. Very similar to adding session management, but handled down in our own UserDetailsService:

import org.springframework.cache.annotation.Cacheable;
import org.springframework.security.core.userdetails.AuthenticationUserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationToken;

public class AuthorizationUserDetailsService implements AuthenticationUserDetailsService<PreAuthenticatedAuthenticationToken> {
    @Override
    @Cacheable(value = "users", key = "#token")
    public UserDetails loadUserDetails(PreAuthenticatedAuthenticationToken token) throws UsernameNotFoundException {
        ...
    }
}

What we have here is a stateless application that uses no session management (no Cookies for you) and yet can cache user details (actually API consumers) as close to the application as we like. Using the caching layer, you can define when and how often your user details expire or are purged, etc.

With caching in place, our API calls to load the Authentication into the SecurityContext do not exhibit such a terrible performance penalty.

Conclusion

In this article, we’ve learned how to implement a pure stateless API with tokens provided in an Authorization header, and defined our own custom scheme for accepting those tokens. We’ve also discussed how this example is very relevant even if you want to enable sessions and consume this API from a mobile app or web browser.

Stateless API Security with Spring Boot, Part 1

Mon, 28 May 2018 00:00:00 +0000

Introduction

In this series of articles, we’ll discuss how to implement pure (stateless) API security for your REST application in Spring Boot using an Authorization header and a custom security scheme.

Basic Authentication

First, let’s discuss the original precursor in the web security space, Basic authentication. Basic uses an Authorization header (defined in RFC 2617) of the form:

credentials        = "Basic" basic-credentials
basic-credentials  = base64-user-pass
base64-user-pass   = <base64 encoding of user-pass>
user-pass          = userid ":" password
userid             = *<TEXT excluding ":">
password           = *TEXT

However, the current acceptable format for this header is defined in the same RFC as:

credentials        = auth-scheme #auth-param
auth-scheme        = token
auth-param         = token "=" ( token | quoted-string )

Notice that these schemes are not compatible. The Basic form is supported for legacy purposes to enable the continued use of the Basic authentication scheme.

Let’s build an application that supports basic authentication first, and then evolve it to meet our end goals for a custom authentication scheme that is compatible with industry standards.

Set Up

Let’s define a build for our project. Here’s a pom.xml skeleton to get us started:

<?xml version="1.0" encoding="utf-8" ?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.insource</groupId>
    <artifactId>basicauth-security-example</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>basicauth-security-example</name>
    <description>Example project for securing REST endpoints with basic auth security.</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.13.RELEASE</version>
        <relativePath />
    </parent>

    <repositories>
        <repository>
            <id>spring-plugins-releases</id>
            <url>http://repo.spring.io/plugins-release</url>
        </repository>
    </repositories>

    <properties>
        <java.version>1.8</java.version>
        <spring-boot.version>1.5.13.RELEASE</spring-boot.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>

        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>${java.version}</source>
                        <target>${java.version}</target>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

Let’s also define an entry point for our application:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

Lastly, let’s define an endpoint we want to be able to secure:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class HelloController {
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World";
    }
}

Add Basic Authentication

Spring Boot makes it easy to create secure-by-default applications. Though they may not be useful beyond the prototyping stage. Let’s add a dependency to our pom:

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

With that change in place, we can run this application and it will be secure out of the box. We must use Basic authentication to access the /api/v1/hello endpoint. The username is “user” by default, with a generated password printed out to the console.

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (v1.5.13.RELEASE)

...
2018-05-28 10:36:37.977  INFO 62012 --- [           main] b.a.s.AuthenticationManagerConfiguration : 

Using default security password: dc458486-180c-4653-a5d7-d4ca5e0eab3b

...

Customize Basic Authentication

If we want to customize the username/password, we can do so by creating an application.yml, as follows:

security:
  basic:
    enabled: true
  user:
    name: user
    password: password

Note that it’s also possible to encrypt the password in this file (and other techniques), which is outside the scope of this article.

We can also customize other aspects of the security model, and this is where we get into the delicate inner workings of Spring Security. Let’s also add a Java configuration:

import org.springframework.boot.autoconfigure.security.SecurityProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.authentication.configurers.provisioning.InMemoryUserDetailsManagerConfigurer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;

@Configuration
@EnableWebSecurity
@EnableConfigurationProperties
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        BasicAuthProperties properties = basicAuthProperties();
        http.requestMatchers().antMatchers(properties.getPath())
            .and()
                .authorizeRequests()
                    .anyRequest().authenticated()
            .and()
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
                .httpBasic().realmName(properties.getRealm())
            .and()
                .csrf().disable();
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        BasicAuthProperties properties = basicAuthProperties();
        InMemoryUserDetailsManagerConfigurer<AuthenticationManagerBuilder> builder = auth.inMemoryAuthentication();
        for (SecurityProperties.User user : properties.getUsers()) {
            builder.withUser(user.getName())
                .password(user.getPassword())
                .roles(user.getRole().toArray(new String[0]));
        }
    }

    @Bean
    public BasicAuthProperties basicAuthProperties() {
        return new BasicAuthProperties();
    }
}

Here, we’ve defined some very elementary configuration to override the defaults. There are two notable aspects of this config.

First, we’ve set the SessionCreationPolicy to STATELESS. This effectively turns off session management and forces the client to authenticate on every API call. We’ve also disabled CSRF to make it clear that we won’t need them. This step is optional as without sessions, we can’t have CSRF tokens, but it just helps to be clear what our intention is with this security model.

Second, we’ve defined a new @ConfigurationProperties of BasicAuthProperties and enabled it with @EnableConfigurationProperties. We’ve also loaded a list of users in memory from external properties. Here’s what that class looks like:

import org.springframework.boot.autoconfigure.security.SecurityProperties;
import org.springframework.boot.context.properties.ConfigurationProperties;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

@ConfigurationProperties("app.security.basic")
public class BasicAuthProperties {
    /**
     * HTTP basic realm name.
     */
    private String realm = "Spring";

    /**
     * Comma-separated list of paths to secure.
     */
    private String[] path = new String[] { "/**" };

    /**
     * Basic authentication users.
     */
    private List<SecurityProperties.User> users = new ArrayList<>(Collections.singletonList(
        new SecurityProperties.User()
    ));

    public String getRealm() {
        return realm;
    }

    public void setRealm(String realm) {
        this.realm = realm;
    }

    public String[] getPath() {
        return path;
    }

    public void setPath(String[] path) {
        this.path = path;
    }

    public List<SecurityProperties.User> getUsers() {
        return users;
    }

    public void setUsers(List<SecurityProperties.User> users) {
        this.users = users;
    }
}

You may also want to add this dependency to generate metadata from your @ConfigurationProperties:

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

This allows us to inject our own configuration into the application.yml file to control our custom Java config. We’ve borrowed just enough from the default config (including SecurityProperties.User) to be consistent. We can add this to application.yml:

app:
  security:
    basic:
      realm: MyRealm
      path: /**
      users:
        - name: user
          password: password
          roles: USER
        - name: admin
          password: admin
          roles: ADMIN

In practice, you’d probably want to get away from hard-coded credentials (though it can work in some instances using profiles and CI/CD pipelines). This is beyond the scope of this article, though I may provide an example of how to do this later.

Conclusion

In this article, we’ve learned how to add Basic authentication to any Spring Boot application. In the next article, we’ll learn how to evolve that into our own custom authentication scheme, in which we provision tokens for API consumers.

Google Cloud Platform, Part 2

Tue, 15 May 2018 00:00:00 +0000

Answer: Don’t. Use Pivotal Cloud Foundry instead.

Look for our next post, where we’ll discuss the transition from Google Cloud to PCF, and the challenges (or complete lack thereof) encountered in that transition.

Google Cloud Platform, Part 1

Tue, 20 Mar 2018 00:00:00 +0000

~> ./start –debug –with-args -Xenv:dev

The Hook: I want to deploy a secure Spring Boot app with a Google Cloud SQL connection to the App Engine Standard environment.

The Line: Know what the @%$&!# you are doing.

The Sinker: Just use spring-cloud-gcp-starter-sql-mysql.

~> cat output.dump | grep INFO | less

This was difficult for several reasons. Here’s the short list:

Local development does not (quite) work like a GCP deployed app
App Engine Standard and App Engine Flexible do not work the same way
App Engine Standard is poorly documented (for certain use cases, like mine)
App Engine Standard requires a WAR file deploy and runs on Jetty, not Tomcat

I assumed App Engine Flexible environment was the way to go, as it’s newer, the docs are better, the examples are more relevant, and the setup seemed easier. It also uses Docker, so I figured this seems like the easy way to get to that utopia state of the same app deployed everywhere.

What I failed to realize is that Flexible environment is ridiculously expensive, has crazy slow deployments, and is not designed for the same use cases. In fact, most of the time, you don’t want to use Flexible environment. That being said, it is vastly superior in almost every way. Apps work the Spring Boot way inside the Docker containers that Google builds. Configuration and setup are vastly simplified, and use yaml files instead of XML deployment descriptors (remember that archaic concept???). Most of Google’s services just work out of the box. Etc.

But Flexible environment is a sledgehammer for the problem of driving a tiny stud into the sparse wasteland of a roof that is my budget-conscious project. I really need a @$%#!& nail gun. That’s what App Engine Standard is. It just isn’t my favorite brand. On account of it sucks.

~> cat output.dump | grep ERROR | more

Let’s cut to the chase. The failure cases I encountered are almost too numerous to list. What I started with was a functional app capable of being deployed to App Engine Flexible, built using the very helpful tutorial on GCP’s documentation site and Hello World GitHub project, among others.

While there were some very specific caveats to even getting this working (which took an embarassingly long time to get working, at least 2-3 evenings), it generally worked well and was only slightly ridiculous. Here’s the setup for this piece to work:

src/main/resources/application.yml

spring:
  application:
    name: hello-world
  jackson:
    serialization:
      write_dates_as_timestamps: false
  jpa:
    open-in-view: true
    show-sql: true
    hibernate:
      ddl-auto: none

security:
  oauth2:
    sso:
      loginPath: /login
    client:
      clientId: my-client-id
      clientSecret: my-client-secret
      accessTokenUri: https://www.googleapis.com/oauth2/v3/token
      userAuthorizationUri: https://accounts.google.com/o/oauth2/auth
      tokenName: oauth_token
      authenticationScheme: query
      clientAuthenticationScheme: form
      scope: profile
    resource:
      userInfoUri: https://www.googleapis.com/userinfo/v2/me
      preferTokenInfo: false

# Spoiler Alert: The following sits innocuously fooling 
# you into believing things that aren't true...
management:
  contextPath: /_ah
  security:
    enabled: false

Here, we’ve set up some basic security configuration using Google as an OAuth2 provider (there are good tutorials for how to do this on the web). The management section seems to disable security for the /_ah requests Google makes, and in App Engine Flexible, things are fine.

Next, we have two profiles with separate configs, setting up a database for local development, and a Google Cloud SQL database for production.

src/main/resources/application-dev.yml

spring:
  datasource:
    driverClassName: com.mysql.jdbc.Driver
    url: jdbc:mysql://localhost:3306/hello-world?useUnicode=true&characterEncoding=utf8&useSSL=false
    username: myuser
    password: mypassword
  jpa:
    database: mysql

src/main/resources/application-prod.yml

spring:
  datasource:
    driverClassName: com.mysql.jdbc.Driver
    url: jdbc:mysql://google/hello-world?useSSL=false&cloudSqlInstance=my-project:us-central1:hello-world&socketFactory=com.google.cloud.sql.mysql.SocketFactory
    username: myuser
    password: mypassword
  jpa:
    database: mysql

In order to make this work for App Engine, I used the following configuration for Flexible environment.

src/main/appengine/app.yaml

runtime: java
env: flex

service: processor

manual_scaling:
  instances: 1

resources:
  memory_gb: 0.768

handlers:
  - url: /.*
    script: this field is required, but ignored

env_variables:
  ENVIRONMENT: "prod"

Notice the environment variable. This was necessary to allow a local development setup that was different from the production deployment. A bit of trickery in the Spring Boot init uses this environment variable:

src/main/java/com/example/java/gettingstarted/HelloworldApplication.java

@SpringBootApplication
public class HelloworldApplication {
  public static void main(String[] args) {
    SpringApplication springApplication = new SpringApplication(HelloworldApplication.class);

    String env = System.getenv("ENVIRONMENT");
    if (env == null) {
      env = "dev";
    }

    springApplication.setAdditionalProfiles(env);
    springApplication.run(args);
  }
}

Assuming the appengine plugin is applied to your build, you just need an extra dependency to add the socket factory for Google Cloud SQL to the classpath at runtime. I added the following to my Gradle build:

dependencies {
    ...
    runtime 'com.google.cloud.sql:mysql-socket-factory'
}

While I won’t delve into the details of why this special piece is needed for Cloud SQL, suffice it to say this handles connecting correctly in a Google Cloud environment.

With this basic app in place (and whatever code you want to do databas-ey things, which I trust you can figure out on your own), you’re good to go in App Engine Flexible. The app is secure and can connect to a cloud database, and /_ah requests made by Google to monitor health work fine. So it would seem.

~> cat output.dump | grep SEVERE > /dev/null

However, when you deploy this totally functional app to App Engine Standard (with a few changes, see below), it fails spectacularly. Here’s the changes I thought I needed.

src/main/webapp/WEB-INF/appengine-web.xml

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <service>hello-world</service>
    <threadsafe>true</threadsafe>
    <runtime>java8</runtime>
    <sessions-enabled>true</sessions-enabled>
    <public-root>/static</public-root>
    <env-variables>
        <env-var name="ENVIRONMENT" value="prod" />
    </env-variables>
    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/classes/logging.properties"/>
    </system-properties>
</appengine-web-app>

The above replaces the app.yaml that Flexible required. You can add additional scaling parameters if you like, see appengine-web.xml Reference.

Then, depending on your build tool (I use Gradle), you may need to make changes to deploy a WAR file as well. See this totally unhelpful example. I shouldn’t say totally unhelpful. It definitely works. But it does not do anything Spring Boot-ish whatsoever, other than stare at you and wave… Creepy.

The problem is that deploying to Standard using the config that worked on Flexible, I can’t connect to a Cloud SQL datasource. My app fails to deploy and start up successfully. Something is missing. And attempting to figure it out via Google was not working.

Somehow, at the end of it all (after nearly a month of procrastinating because this problem was so frustrating to work out), I found the spring-cloud-gcp project. After looking at the source code, I think I’ve worked out the missing piece, but it’s still a theory. However, the simple fix was to add a starter from this project to my classpath, which effectively adds spring-cloud-gcp-autoconfigure.jar containing an implementation or two of CloudSqlJdbcInfoProvider, whatever that is.

I added the following to my Gradle build:

repositories {
    ...
    maven {
        url "https://repo.spring.io/milestone"
    }
}

dependencyManagement {
    imports {
        mavenBom 'org.springframework.cloud:spring-cloud-gcp-dependencies:1.0.0.M2'
    }
}

dependencies {
    ...
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
    compileOnly 'org.slf4j:jul-to-slf4j'
    compileOnly 'javax.servlet:javax.servlet-api'
    runtime 'org.springframework.cloud:spring-cloud-gcp-starter-sql-mysql'
}

The first three dependencies are just changes going from Flexible to Standard, which runs in a Jetty container instead of embedded Tomcat. More on this next time. The last piece adds the aforementioned starter for mysql to the classpath at runtime. We do need a few config changes. Here’s the prod config:

src/main/resources/application-prod.yml

spring:
  datasource:
#    driverClassName: com.mysql.jdbc.Driver
#    url: jdbc:mysql://google/hello-world?useSSL=false&cloudSqlInstance=my-project:us-central1:hello-world&socketFactory=com.google.cloud.sql.mysql.SocketFactory
    username: myuser
    password: mypassword
  jpa:
    database: mysql
  cloud:
    gcp:
      project-id: my-project
      sql:
        database-type: mysql
        database-name: hello-world
        instance-connection-name: my-project:us-central1:hello-world

The theory is that the CloudSqlJdbcInfoProvider actually configures the two commented out settings. What looks to happen is that the driverClassName actually gets set to com.mysql.jdbc.GoogleDriver, which I don’t even know where that comes from. It isn’t on the classpath. It’s just a mystery. I suspect this is actually the magic, which could make this starter dependency optional at best, though it could have other uses, so your mileage may vary.

Now, there’s one last issue with App Engine Standard. Remember the config for Spring Boot from earlier, with the comment about innocuous settings fooling you into believing things that aren’t true? Yeah… About that. So the management section does not seem to apply in the Standard environment. Possibly because of the war file deployment, additional Spring Boot features aren’t available, feedback welcome on what causes it. But suffice it to say, the /_ah requests made by Google fail. Why? Because security.

So you’ll need to add a couple of unsecured endpoints that can respond to the App Engine Standard health requests. These are /_ah/start and /_ah/stop.

@RestController
public class HealthController {
  @GetMapping("/_ah/start")
  @PreAuthorize("hasRole('ANONYMOUS')")
  public String start() {
    return "OK";
  }

  @GetMapping("/_ah/stop")
  @PreAuthorize("hasRole('ANONYMOUS')")
  public String stop() {
    return "OK";
  }
}

You will want to add these to your unsecured routes as well.

@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
  @Override
  public void configure(HttpSecurity http) {
    http
      .authorizeRequests()
      .antMatchers("/_ah/*")
      .permitAll();
  }
}

This works in App Engine Standard. FINALLY!!!

Now, there are a few nasty problems left to deal with. I’ll save those for next time.

Hint: Try running this pile of mess from your IDE after converting to App Engine Standard. Double Hint: You can’t!!!