www.baeldung.

com
1
 Table of Contents

1. Overview .......................................................................................................................................... 1

2. The Resources ............................................................................................................................... 2

3. REST API ............................................................................................................................................ 3

4. Security Configuration .............................................................................................................. 6

5. Cloud Configuration ................................................................................................................... 8

5.1. Configuration Server .................................................................................................. 9

5.2. Discovery Server .......................................................................................................... 11

5.3. Gateway Server ............................................................................................................. 15

5.4. REST APIs .......................................................................................................................... 18

6. Session Configuration ............................................................................................................... 20

7. Test REST API ................................................................................................................................. 22

8. Run ...................................................................................................................................................... 26

9. Conclusion ....................................................................................................................................... 27
1. Overview

In this guide, we’ll focus on building out a simple, but fully working base for a
microservice architecture with Spring Boot and Spring Cloud.

If you want to dig further into Spring Cloud, definitely go over our Spring Cloud
Articles.

The system we’re going to start building here is a simple library application,
primarily focused on books and reviews. Let’s start with the two REST APIs:

• Book API
• Rating API

1
2. The Resources

First, let’s take a look at our resources Book:

1 public class Book {

2 private long id;
3     private String title;
4     private String author;
5  
6     // standard getters and setters
7 }

And of course the Rating resource, backing the second API:

1 public class Rating {

2     private long id;
3     private Long bookId;
4     private int stars;
5
6     // standard getters and setters
7 }

2
3. REST API

Now, we’ll bootstrap the two simple APIs – /books and /ratings.
First, let’s explore our Books API:

1 @RestController
2 @RequestMapping("/books")
3 public class BookController {
4 @Autowired
5 private BookService bookService;
6
7 @GetMapping
8 public List<Book> findAllBooks() {
9 return bookService.findAllBooks();
10 }
11
12 @GetMapping("/{bookId}")
13 public Book findBook(@PathVariable Long bookId) {
14 return bookService.findBookById(bookId);
15 }
16
17 @PostMapping
18 public Book createBook(@RequestBody Book book) {
19 return bookService.createBook(book);
20 }
21
22 @DeleteMapping("/{bookId}")
23 public void deleteBook(@PathVariable Long bookId) {
24 bookService.deleteBook(bookId);
25 }
26 @PutMapping("/{bookId}")
27 public Book updateBook(@RequestBody Book book, @PathVariable Long bookId) {
28 return bookService.updateBook(book, bookId);
29 }
30 @PatchMapping("/{bookId}")
31 public Book updateBook(
32 @RequestBody Map<String, String> updates,
33 @PathVariable Long bookId) {
34 return bookService.updateBook(updates, bookId);
35 }
36 }

3
And similarly the RatingController:

1 @RestController
2 @RequestMapping("/ratings")
3 public class RatingController {
4  
5     @Autowired
6     private RatingService ratingService;
7  
8     @GetMapping
9     public List<Rating> findRatingsByBookId(
10       @RequestParam(required = false, defaultValue = "0") Long bookId) {
11         if (bookId.equals(0L)) {
12             return ratingService.findAllRatings();
13         }
14         return ratingService.findRatingsByBookId(bookId);
15     }
16  
17     @PostMapping
18     public Rating createRating(@RequestBody Rating rating) {
19         return ratingService.createRating(rating);
20     }
21  
22     @DeleteMapping("/{ratingId}")
23     public void deleteRating(@PathVariable Long ratingId) {
24         ratingService.deleteRating(ratingId);
25     }
26  
27     @PutMapping("/{ratingId}")
28     public Rating updateRating(@RequestBody Rating rating, @PathVariable Long ratingId) {
29         return ratingService.updateRating(rating, ratingId);
30     }
31     @PatchMapping("/{ratingId}")
32     public Rating updateRating(
33       @RequestBody Map<String, String> updates,
34       @PathVariable Long ratingId) {
35         return ratingService.updateRating(updates, ratingId);
36     }
37 }

4
Notice that we’re not focusing on persistence here – the main focus is the API
each application is exposing.
Each API has its own, separate Boot application and is deployment entirely
independently of anything else.
When deployed locally, the APIs will be available at:

1 http://localhost:8080/book-service/books

2 http://localhost:8080/rating-service/ratings

5
4. Security Configuration

The next step here is to secure the two APIs. Although we may choose to
upgrade to an OAuth2 + JWT implementation later on, a good place to start is
only using form login. We will see this in section 5.3 when we see the security
configuration of the gateway.
First, our Book application security configuration:

1 @EnableWebSecurity
2 @Configuration
3 public class SecurityConfig extends WebSecurityConfigurerAdapter {
4
5 @Autowired
6 public void configureGlobal1(AuthenticationManagerBuilder auth)
7 throws Exception {
8 auth.inMemoryAuthentication();
9 }
10
11 @Override
12 protected void configure(HttpSecurity http) throws Exception {
13 http.httpBasic()
14 .disable()
15 .authorizeRequests()
16 .antMatchers(HttpMethod.GET, "/books").permitAll()
17 .antMatchers(HttpMethod.GET, "/books/*").permitAll()
18 .antMatchers(HttpMethod.POST, "/books").hasRole("ADMIN")
19 .antMatchers(HttpMethod.PATCH, "/books/*").hasRole("ADMIN")
20 .antMatchers(HttpMethod.DELETE, "/books/*").hasRole("ADMIN")
21 .anyRequest().authenticated()
22 .and()
23 .csrf()
24 .disable();
25 }
26 }

6
And then the Rating configuration:

1 @EnableWebSecurity
2 @Configuration
3 public class SecurityConfig extends WebSecurityConfigurerAdapter {
4
5 @Autowired
6 public void configureGlobal1(AuthenticationManagerBuilder auth)
7 throws Exception {
8 auth.inMemoryAuthentication();
9 }
10
11 @Override
12 protected void configure(HttpSecurity http) throws Exception {
13 http.httpBasic()
14 .disable()
15 .authorizeRequests()
16 .regexMatchers("^/ratings\\?bookId.*$").authenticated()
17 .antMatchers(HttpMethod.POST,"/ratings").authenticated()
18 .antMatchers(HttpMethod.PATCH,"/ratings/*").hasRole("ADMIN")
19 .antMatchers(HttpMethod.DELETE,"/ratings/*").hasRole("ADMIN")
20 .antMatchers(HttpMethod.GET,"/ratings").hasRole("ADMIN")
21 .anyRequest().authenticated()
22 .and()
23 .csrf()
24 .disable();
25 }
26 }

Because the APIs are simple, we can use global matchers right in the security
config. However, as they become more and more complex, we should look towards
migrating these to a method level annotation implementation.

Right now the security semantics are very simple:

• Anyone can read Resources

• Only admins can modify resources

7
5. Cloud Configuration

Now, with our two APIs running independently, it’s time to look at the using Spring
Cloud and bootstrap some very useful components in our microservice topology:

1. Configuration Server – provides, manages and centralize the configuration to

externalize the configuration of our different modules
2. Discovery Server – enable applications to find each other efficiently and with
flexibility
3. Gateway Server – acts as a reverse proxy and hide complexity of our system by
providing all our APIs on one port
4. Two REST APIs: Books API and Ratings API

We’re going to use Spring Initializr to bootstrap these 3 new applications quickly.

8
5.1. Configuration Server

First, we will setup the configuration server, we will need Cloud Config, Eureka
and Security:

1 <dependency>
2 <groupId>org.springframework.cloud</groupId>
3 <artifactId>spring-cloud-config-server</artifactId>
4 </dependency>
5 <dependency>
6 <groupId>org.springframework.cloud</groupId>
7 <artifactId>spring-cloud-starter-eureka</artifactId>
8 </dependency>
9 <dependency>
10 <groupId>org.springframework.boot</groupId>
11 <artifactId>spring-boot-starter-security</artifactId>
12 </dependency>

9
Next, we need to use @EnableConfigServer to make our configuration server
discoverable via Eureka client – as follows:

1 @SpringBootApplication
2 @EnableConfigServer
3 @EnableEurekaClient
4 public class ConfigApplication {...}

And here is application.properties:

1 server.port=8081
2 spring.application.name=config
3 spring.cloud.config.server.git.uri=file:///${user.home}/application-config
4 eureka.client.region=default
5 eureka.client.registryFetchIntervalSeconds=5
6 eureka.client.serviceUrl.defaultZone=
7 http://discUser:discPassword@localhost:8082/eureka/
8 security.user.name=configUser
9 security.user.password=configPassword
10 security.user.role=SYSTEM

Next, we need to create a local Git repository application-config in our HOME

directory to hold our configuration files:

1 cd ~
2 mkdir application-config
3 cd application-config
4 git init

Note: We are using local Git repository for testing purpose.

10
5.2. Discovery Server

For the discovery server, we need Eureka, Cloud Config Client and Security:

1 <dependency>
2 <groupId>org.springframework.cloud</groupId>
3 <artifactId>spring-cloud-starter-eureka-server</artifactId>
4 </dependency>
5 <dependency>
6 <groupId>org.springframework.cloud</groupId>
7 <artifactId>spring-cloud-starter-config</artifactId>
8 </dependency>
9 <dependency>
10 <groupId>org.springframework.boot</groupId>
11 <artifactId>spring-boot-starter-security</artifactId>
12 </dependency>

We will configure our discovery server by firstly adding @EnableEurekaServer

annotation:

1 @SpringBootApplication
2 @EnableEurekaServer
3 public class DiscoveryApplication {...}

11
And make sure we also need to secure our discovery server endpoints:

1 @Configuration
2 @EnableWebSecurity
3 @Order(1)
4 public class SecurityConfig extends WebSecurityConfigurerAdapter {
5    @Autowired
6     public void configureGlobal(AuthenticationManagerBuilder auth) {
7      auth.inMemoryAuthentication()
8             .withUser("discUser")
9             .password("discPassword")
10             .roles("SYSTEM");
11    }
12   
13    @Override
14    protected void configure(HttpSecurity http) {
15        http
16        .sessionManagement()
17          .sessionCreationPolicy(SessionCreationPolicy.ALWAYS).and()
18        .requestMatchers().antMatchers("/eureka/**").and()
19        .authorizeRequests()
20          .antMatchers("/eureka/**").hasRole("SYSTEM")
21          .anyRequest().denyAll().and()
22        .httpBasic().and()
23        .csrf().disable();
24    }
25 }

12
and also secure the Eureka dashboard:

1 @Configuration
2 public static class AdminSecurityConfig extends WebSecurityConfigurerAdapter {
3     @Override
4     protected void configure(HttpSecurity http) {
5        http
6        .sessionManagement()
7          .sessionCreationPolicy(SessionCreationPolicy.NEVER).and()
8        .httpBasic().disable()
9        .authorizeRequests()
10          .antMatchers(HttpMethod.GET, "/").hasRole("ADMIN")
11          .antMatchers("/info", "/health").authenticated()
12          .anyRequest().denyAll().and()
13        .csrf().disable();
14    }
15 }

Now, we will add bootstrap.properties in our discovery server resources folder

as follows:

1 spring.cloud.config.name=discovery
2 spring.cloud.config.uri=http://localhost:8081
3 spring.cloud.config.username=configUser
4 spring.cloud.config.password=configPassword

Finally, we will add discovery.properties in our application-config Git

repository:

1 spring.application.name=discovery
2 server.port=8082
3 eureka.instance.hostname=localhost
4 eureka.client.serviceUrl.defaultZone=
5   http://discUser:discPassword@localhost:8082/eureka/
6 eureka.client.register-with-eureka=false
7 eureka.client.fetch-registry=false
8 spring.redis.host=localhost
9 spring.redis.port=6379

13
Note that:
• We are using @Order(1) as we have to security configurations for discovery
server, one for the endpoints and the other for the dashboard
• spring.cloud.config.name should be the same as discovery server properties
file in configuration repository
• We have to provide spring.cloud.config.uri in the discovery server bootstrap
properties to be able to obtain full configuration from configuration server

14
5.3. Gateway Server

To setup the gateway server we need Cloud Config Client, Eureka Client,
Zuul and Security:

1 <dependency>
2     <groupId>org.springframework.cloud</groupId>
3     <artifactId>spring-cloud-starter-config</artifactId>
4 </dependency>
5 <dependency>
6     <groupId>org.springframework.cloud</groupId>
7     <artifactId>spring-cloud-starter-eureka</artifactId>
8 </dependency>
9 <dependency>
10     <groupId>org.springframework.cloud</groupId>
11     <artifactId>spring-cloud-starter-zuul</artifactId>
12 </dependency>
13 <dependency>
14     <groupId>org.springframework.boot</groupId>
15     <artifactId>spring-boot-starter-security</artifactId>
16 </dependency>

Next, we need to need to configure our gateway server as follows:

1 @SpringBootApplication
2 @EnableZuulProxy
3 @EnableEurekaClient
4 public class GatewayApplication {}

15
And add a simple security configuration:

1 @EnableWebSecurity
2 @Configuration
3 public class SecurityConfig extends WebSecurityConfigurerAdapter {
4     @Autowired
5     public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
6         auth.inMemoryAuthentication()
7             .withUser("user").password("password").roles("USER")
8             .and()
9             .withUser("admin").password("admin").roles("ADMIN");
10     }
11  
12     @Override
13     protected void configure(HttpSecurity http) throws Exception {
14         http
15         .authorizeRequests()
16           .antMatchers("/book-service/books").permitAll()
17           .antMatchers("/eureka/**").hasRole("ADMIN")
18           .anyRequest().authenticated().and()
19         .formLogin().and()
20         .logout().permitAll().and()
21         .csrf().disable();
22     }
23 }

We also need to add bootstrap.properties in our gateway server resources

folder as follows:

1 spring.cloud.config.name=gateway
2 spring.cloud.config.discovery.service-id=config
3 spring.cloud.config.discovery.enabled=true
4 spring.cloud.config.username=configUser
5 spring.cloud.config.password=configPassword
6 eureka.client.serviceUrl.defaultZone=
7   http://discUser:discPassword@localhost:8082/eureka/

16
Finally, we will add gateway.properties in our application-config Git repository:

1 spring.application.name=gateway
2 server.port=8080
3 eureka.client.region = default
4 eureka.client.registryFetchIntervalSeconds = 5
5 management.security.sessions=always
6  
7 zuul.routes.book-service.path=/book-service/**
8 zuul.routes.book-service.sensitive-headers=Set-Cookie,Authorization
9 hystrix.command.book-service.execution.isolation.thread
10   .timeoutInMilliseconds=600000
11 zuul.routes.rating-service.path=/rating-service/**
12 zuul.routes.rating-service.sensitive-headers=Set-Cookie,Authorization
13 hystrix.command.rating-service.execution.isolation.thread
14   .timeoutInMilliseconds=600000
15 zuul.routes.discovery.path=/discovery/**
16 zuul.routes.discovery.sensitive-headers=Set-Cookie,Authorization
17 zuul.routes.discovery.url=http://localhost:8082
18 hystrix.command.discovery.execution.isolation.thread
19   .timeoutInMilliseconds=600000
20  
21 spring.redis.host=localhost
22 spring.redis.port=6379

Note: We are using zuul.routes.book-service.path to route any request that

comes in on /book-service/** to our Book Service application, same applies for
our Rating Service

17
5.4. REST APIs

We will need the same setup for both APIs: Config Client, Eureka, JPA, Web
and Security:

1 <dependency>
2 <groupId>org.springframework.cloud</groupId>
3 <artifactId>spring-cloud-starter-config</artifactId>
4 </dependency>
5 <dependency>
6 <groupId>org.springframework.cloud</groupId>
7 <artifactId>spring-cloud-starter-eureka</artifactId>
8 </dependency>
9 <dependency>
10 <groupId>org.springframework.boot</groupId>
11 <artifactId>spring-boot-starter-data-jpa</artifactId>
12 </dependency>
13 <dependency>
14 <groupId>org.springframework.boot</groupId>
15 <artifactId>spring-boot-starter-web</artifactId>
16 </dependency>
17 <dependency>
18 <groupId>org.springframework.boot</groupId>
19 <artifactId>spring-boot-starter-security</artifactId>
20 </dependency>

We will also use @EnableEurekaClient for both APIs- as follows:

1 @SpringBootApplication
2 @EnableEurekaClient
3 public class ServiceApplication {...}

18
Here is our first resource service “Book Service” properties configuration
book-service.properties which will be at application-config repository:

1 spring.application.name=book-service
2 server.port=8083
3 eureka.client.region=default
4 eureka.client.registryFetchIntervalSeconds=5
5 management.security.sessions=never

and here is the Book Service bootstrap.properties which will be in our book
service resources folder:

1 spring.cloud.config.name=book-service
2 spring.cloud.config.discovery.service-id=config
3 spring.cloud.config.discovery.enabled=true
4 spring.cloud.config.username=configUser
5 spring.cloud.config.password=configPassword
6 eureka.client.serviceUrl.defaultZone=
7 http://discUser:discPassword@localhost:8082/eureka/

Similarly here is our second service “Rating Service” rating-service.properties:

1 spring.application.name=rating-service
2 server.port=8084
3 eureka.client.region=default
4 eureka.client.registryFetchIntervalSeconds=5
5 management.security.sessions=never

and bootstrap.properties:

1 spring.cloud.config.name=rating-service
2 spring.cloud.config.discovery.service-id=config
3 spring.cloud.config.discovery.enabled=true
4 spring.cloud.config.username=configUser
5 spring.cloud.config.password=configPassword
6 eureka.client.serviceUrl.defaultZone=
7   http://discUser:discPassword@localhost:8082/eureka/

19
6. Session Configuration

We will share sessions between different services in our system using Spring
Session. Sharing sessions enable logging users in our gateway service and
propagate that authentication to the other services

First, we need to add the following dependencies to discovery server, gateway

server, book service and rating service:

1 <dependency>
2 <groupId>org.springframework.session</groupId>
3     <artifactId>spring-session</artifactId>
4 </dependency>
5 <dependency>
6     <groupId>org.springframework.boot</groupId>
7     <artifactId>spring-boot-starter-data-redis</artifactId>
8 </dependency>

We need to add session configuration to our discovery server and REST APIs:

1 @EnableRedisHttpSession
2 public class SessionConfig
3 extends AbstractHttpSessionApplicationInitializer {
4 }

For our gateway server, it will be slightly different:

1 @Configuration
2 @EnableRedisHttpSession(redisFlushMode = RedisFlushMode.IMMEDIATE)
3 public class SessionConfig extends AbstractHttpSessionApplicationInitializer {
4 }

20
We also add a simple filter to our gateway server to forward the session so that
authentication will propagate to another service after login:

1 @Component
2 public class SessionSavingZuulPreFilter
3   extends ZuulFilter {
4   
5     @Autowired
6     private SessionRepository repository;
7   
8     @Override
9     public boolean shouldFilter() {
10         return true;
11     }
12   
13     @Override
14     public Object run() {
15         RequestContext context = RequestContext.getCurrentContext();
16         HttpSession httpSession = context.getRequest().getSession();
17         Session session = repository.getSession(httpSession.getId());
18   
19         context.addZuulRequestHeader(
20           "Cookie", "SESSION=" + httpSession.getId());
21         return null;
22     }
23   
24     @Override
25     public String filterType() {
26         return "pre";
27     }
28   
29     @Override
30     public int filterOrder() {
31         return 0;
32     }
33 }

21
7. Test REST API

Finally, we will test our REST API

First, a simple setup:

1 private final String ROOT_URI = "http://localhost:8080";

2 private FormAuthConfig formConfig
3   = new FormAuthConfig("/login", "username", "password");
4  
5 @Before
6 public void setup() {
7     RestAssured.config = config().redirect(
8       RedirectConfig.redirectConfig().followRedirects(false));
9 }

Next, let’s get all books:

1 @Test
2 public void whenGetAllBooks_thenSuccess() {
3     Response response = RestAssured.get(ROOT_URI + "/book-service/books");
4   
5     Assert.assertEquals(HttpStatus.OK.value(), response.getStatusCode());
6     Assert.assertNotNull(response.getBody());
7 }

Then, try to access protected resource without login:

1 @Test
2 public void whenAccessProtectedResourceWithoutLogin_thenRedirectToLogin() {
3     Response response = RestAssured.get(ROOT_URI + "/book-service/books/1");
4   
5     Assert.assertEquals(HttpStatus.FOUND.value(), response.getStatusCode());
6     Assert.assertEquals("http://localhost:8080/login",
7       response.getHeader("Location"));
8 }

22
Then, login and create new Book:

1 @Test
2 public void whenAddNewBook_thenSuccess() {
3     Book book = new Book();
4 book.setTitle("How to spring cloud");
5 book.setAuthor("Baeldung");
6
7     Response bookResponse = RestAssured.given()
8 .auth()
9       .form("admin", "admin", formConfig)
10 .and()
11       .contentType(ContentType.JSON)
12       .body(book)
13       .post(ROOT_URI + "/book-service/books");
14
15     Book result = bookResponse.as(Book.class);
16   
17     Assert.assertEquals(HttpStatus.OK.value(), bookResponse.getStatusCode());
18     Assert.assertEquals(book.getAuthor(), result.getAuthor());
19     Assert.assertEquals(book.getTitle(), result.getTitle());
20 }

and then access the protected resource after login:

1 @Test
2 public void whenAccessProtectedResourceAfterLogin_thenSuccess() {
3     Response response = RestAssured.given().auth()
4       .form("user", "password", formConfig)
5       .get(ROOT_URI + "/book-service/books/1");
6   
7     Assert.assertEquals(HttpStatus.OK.value(), response.getStatusCode());
8     Assert.assertNotNull(response.getBody());
9 }

23
Now, we will create new Rating:

1 @Test
2 public void whenAddNewRating_thenSuccess() {
3     Rating rating = new Rating();
4 rating.setBookId(1L);
5 rating.setStars(4);
6
7     Response ratingResponse = RestAssured.given()
8 .auth()
9       .form("admin", "admin", formConfig)
10 .and()
11       .contentType(ContentType.JSON)
12       .body(rating)
13       .post(ROOT_URI + "/rating-service/ratings");
14
15     Rating result = ratingResponse.as(Rating.class);
16   
17     Assert.assertEquals(HttpStatus.OK.value(), ratingResponse.getStatusCode());
18     Assert.assertEquals(rating.getBookId(), result.getBookId());
19     Assert.assertEquals(rating.getStars(), result.getStars());
20 }

Now try access admin protected Rating resource:

1 @Test
2 public void whenAccessAdminProtectedResource_thenForbidden() {
3     Response response = RestAssured.given().auth()
4       .form("user", "password", formConfig)
5       .get(ROOT_URI + "/rating-service/ratings");
6   
7     Assert.assertEquals(HttpStatus.FORBIDDEN.value(), response.getStatusCode());
8 }

24
Then access protected Rating by login using admin:

1 @Test
2 public void whenAdminAccessProtectedResource_thenSuccess() {
3     Response response = RestAssured.given().auth()
4       .form("admin", "admin", formConfig)
5       .get(ROOT_URI + "/rating-service/ratings");
6   
7     Assert.assertEquals(HttpStatus.OK.value(), response.getStatusCode());
8     Assert.assertNotNull(response.getBody());
9 }

Finally, access discovery resources as the admin:

1 @Test
2 public void whenAdminAccessDiscoveryResource_thenSuccess() {
3     Response response = RestAssured.given().auth()
4       .form("admin", "admin", formConfig)
5       .get(ROOT_URI + "/discovery");
6   
7     Assert.assertEquals(HttpStatus.OK.value(), response.getStatusCode());
8 }

25
8. Run

• Create a local Git repository application-config in you HOME directory.

• Add the configuration properties files.
• Make sure to commit all changes in the local Git repository before running the
servers.

1 git add -A

2 git commit -m "the initial configuration"

• Make sure to run the modules in the following order:

• Run the configuration server “port 8081”
• Then, run discovery server “port 8082”
• After that, run gateway server “port 8080”
• Finally, run resource servers “port 8084 , 8083”

26
9. Conclusion

We discussed how to build a simple REST API using Spring Boot and Spring Cloud

The source code for all modules presented is available over on GitHub.

27