This article introduces the core feature set of JHipster UAA, in particular building HTTP clients for service-to-service communication, security configuration and testing.
It has been a while since my last article. For those, who might be crazy enough to follow my blog should remember the statement of my last article on how to get started with JHipster microservices, which became a core feature since version 3.0.
My statement was:
I am considering to implement a UAA using JHipster and spring-cloud-security and spring-cloud-oauth2, as I did in my last tutorial.
To review, how I got to this statement, I was writing about how Ribbon and Hystrix can be used in order to let one microservice being able to request resources from another microservice, without going over the gateway, and being aware of service failure, load balancing and so on. But I left this without any considerations on security, as with the JWT solution, there wasn’t any suitable workaround, which would do that job in a proper way.
So, let me quickly what happened the last 6 months:
When my last JHipster article made some rounds over the world wide web, I generated off some demo microservice setup and moved the user domain from the gateway to one microservice I called “jhipster-uaa”. After this, I performed the steps from my spring OAuth2 security article, so I had an
AuthorizationServerConfigurerAdapter built in that UAA and turned
WebSecurityConfigurerAdapter from the microservices into a
ResourceServerConfigurerAdapter. This worked perfectly, so I made some screen:
and Julien Dubois, lead developer of JHipster, asked me to document this. I did a little more than that: contributing the entire setup including further updates for declarative service communication and testing tools directly to JHipster, as my aim was to make this overcomplex stuff adaptable easily for all developers.
In other words, I want to:
I want to have secure microservices, which can scale
be open and easy to use for all JHipster users, as well as spring developers, who just can generate JHipster code to look how it works. So after 6 months of different works on the generators, JHipster released my official documentation on using JHipster UAA, so I can proudly sum up my thoughts from late march this year, because now it is really simple to use.
To use the new features, the service generation differs from the way I described it in march. Let’s walk to the major differences:
- It’s now required to generate one more service, called “uaa”. The very first question of
yo jhipsterwill provide a new type of application: JHipster UAA server
- For all other services, there will be a question: “which kind of authentication” to use. Here the “uaa” option is required.
- As for now, it is better to use Hazelcast as hibernate cache (I will explain this a bit more below)
You can find the final project in my GitHub repository
To start of quickly, first use the build script in root:
and then just start the whole setup using:
Using these settings, the gateway will not contain the user and account endpoints anymore, since they are now in the UAA. Furthermore, spring cloud security is used in order to provide security. At this point, there isn’t a big difference to the JWT authentication type, to do all the other stuff, which was possible until today.
secure service-to-service communication
In part 2 I showed how to use Ribbon and Hystrix manually with
RestTemplate, to let the “foo-service” request data from “bar-service”. To make this secure, now the UAA can be used. I will first describe, how we could that in theory, following the pattern as we did it last time.
First, we would need a new
RestTemplate (with Ribbon and Hystrix) to communicate with the UAA. In addition, we need to setup basic authentication with username and password “internal”, to call the following url: http://uaa/oauth/token using POST and one field “grant_type” with value “client_credentials”. As you might recognize, we are about authenticating the microservice for the OAuth client named “internal”. The response will be an access token. Now, we get back to our REST client for “bar-service”, and add an authorization header with that access token as “Bearer”.
Despite this is a lot of work, we now achieved a secure communication, as the foo service is now authenticated as a service principal, which
has an valid access token. The “bar-service” now is able to setup access controll configuration based on roles and scope.
This sounds awesome, doesn’t it? I thought of this is not straight forward enough, since security is basic, and should not be a leg braking task for development. This is where the Feign project comes into play. When thinking about feign, I always have an association with the moment, when I firstly realized, how “spring-data-jpa” is working, when only an interface has to be defined as repository, without doing any real implementation.
Something similar does feign to you. We just define some interface, using exactly the same
@RequestMapping annotations as used for the endpoints in the service we are going to consume, and voila: some magic does the implementation for us…including Ribbon, Hystrix and (with some additional support from JHipster UAA) access token requesting for uaa.
Assuming we got an JHipster UAA generated application setup as it is out of the box, there are now two steps, to get it working
making a representation of “Bar” in “Foo”
Ok, this is really obvious, but we need that less code, that I keep some extra lines in my article on that :)
1 2 3 4 5 6 7 8 9 10 11
You just can copy&paste that from Foo, by removing the JPA and validation annotations.
declaring a authorized feign client
1 2 3 4 5
and we are done. We now can just
@Inject that client to get things working. In order to make some demo endpoint on “foo-service”, we may define a REST controller like this:
1 2 3 4 5 6 7 8 9 10 11 12
Of cause, this is just one example. This can be done with some services and so on.
Now, what is that
@AuthorizedFeignClient annotation? This is some JHipster magic in order to call the UAA server to get a token (if needed, it’s stored in memory until it expires). If it is still not clear: it is possible to use
@FeignClient without any predefined configuration as it is, without any JHipster magic, for every other purpose. This is a nice feature now available to all JHipster microservice applications, if you are already familiar with feign.
One more note on
@AuthorizedFeignClient, I used the “name” property of feign client declaration, in order to make it working. For now, the other notations, such as
@AuthorizedFeignClient(value = "bar") are not working, due to a bug inside spring.
using Hazelcast to the rescue
In my recent articles I preferred to generate my projects with a minimal setup, in particular without 2nd level cache. For the moment, there is some issue where a microservice tries to resolve the “uaa” endpoint in configuration phase, to fetch the public key to sign incoming JWTs. Without 2nd level cache this happens to fast, so there aren’t any registered services to load balance, because they weren’t retrieved. Using Hazelcast is a dirty fix for that.
Despite this solution is quite new to the official JHipster release, it is already battle tested in several applications, where I used my own JHipster branch to generate the application. This led to two advanced topics about testing, which made the UAA feature set much more usable in production.
As we can assume, feign clients are generally working, it makes no sense to enable then during test (what would mean we are testing that feign itself works). Instead of this, we use some simple mocking technique, to fake the client, to actually test the components using them.
Lets consider some service like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
note: the FooRepository should have a findOneByValue method returning
Optional<Foo> and Foo should have an extra constructor
This service looks up for existing “bars”, and syncs “foos” with the same value.
To test that this service is working properly, we need to write the following test:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
Obviously, this test would fail the most time in a real environment without the mocking, as it logically depends on the contents of bar service, if not exactly these value exists. We use
@MockBean to overwrite the actual injection of the bar client, and mock the return behavior using
given(...).willReturn(...) from Mockito.
Security testing using
Another desired testing technique is, to test how the application behaves when access control configuration is applied.
In order to make not to much work on this scenario, we look into the
UaaConfiguration and see, that per default internal clients get the scope “web-app” granted. To make a RBAC style restriction, we need to apply the following rule in
which enforces all request to “/api/foos” exclusively granted for internal clients.
To test this configuration holds, we write the following test class.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
I really hope “my considering of writing some UAA for JHipster” lead to some mighty tools, which demystify the usage of OAuth 2 in context of microservice security solution, which easily can be used for JHipster (or just spring based) applications.
This contribution also lead finally to a positive voting for my membership at the JHipster core developer team, which is a great honor to me.
As usual I am open for questions and feedback in the comments section as well as on StackOverflow using the “jhipster” or “spring-cloud-security” tag or on GitHub.
For the further articles the following topics are in my pipeline:
- GitLab CI + dokku setup (complete deployment pipeline)
- spring cloud consul as alternative to Eureka
Have a great upcoming weekend!