Part of a possible Microservice Architecture

API Gateway — Spring Cloud Gateway

In microservice applications (in this case Spring Boot microservices), a common choice is to use an API gateway as the entry point to the outside world. All (or almost all) calls from the browser — or from an external service — pass through the gateway before going to an API of a microservice. This layer typically includes various security controls, authentication, caching and so on.

The current standard de facto promoted by Spring for implementing an API gateway is Spring Cloud Gateway which is a great choice because integrate many features out of the box (as always with few lines of configuration) and it’s also ready to be used as a Reactive Application (instead that the typical MVC application as Spring Boot). As spring says:

Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux. It does not work in a traditional Servlet Container or when built as a WAR.

With an API Gateway there are basically two patterns that can be used for authentication:

1. API Gateway acts as an OAuth2 Client: in this case, any unauthenticated incoming request will initiate a flow to obtain a valid Token. Once the token is acquired by the gateway, it is then used when sending requests to a backend service. The API Gateway interacts with the authorization server to obtain access and refresh tokens and stores them securely.
2. API Gateway acts as an OAuth 2.0 Resource Server: here the gateway enforcing that each request has a valid access token before it is sent to a back-end service. Typically, the token is sent from the backend to the frontend and then the frontend sends the token provided for each call

In this example we are in the first scenario where the API Gateway acts as an OAuth2 Client and the Frontend (can we say the external world) never talk with microservices but every request pass from the API Gateway to the others microservices.

Type of authentication — OIDC

With microservice architectures, one of the most used authentication type is OIDC (OpenID Connect), which adds authentication functionality to the OAuth2 protocol used for the authorization part with JWT Token. An open source popular identity provider used for this purpose is Keycloak. Other commercial OIDC alternatives include Okta, AUth0, Microsoft Azure Active Directory (AD), AWS Cognito and so on.

How protect microservices from outside — JWT

In business scenarios, security is always a key concept. It’s important to have different layers of security and one of them implies protect microservices with authentication. At microservice level, authentication is not intended as the authentication used for identify users of an application. Authentication for a microservice means receive request authenticated and in this example means that all calls received from the gateway must be authenticated. A common example of authentication on microservices is JWT tokens. Endpoints exposed by microservices will only be accessible if a valid JWT token is provided.

The role of Keycloak — Identity Provider and Authorization Server

In this example Keycloak have an important role because at API Gateway level acts as Identity Provider managing User’s Authentication (In this way, no user credentials will be stored in the application DB), while at microservice level acts as Authorization Server authenticating the incoming request from the gateway. In other word, in microservices is Keycloak that determine if the JWT token is valid or not and make APIs reachable.

Security, Authentication and Authorization — Spring Security

It is challenging to imagine an application like this without Spring Security, which is the standard for managing authentication and authorization in Spring Boot applications and handling security aspects in general. In this case it is Spring Security that will take care of the configuration to manage what has been said so far.

Authentication

In this example, the authentication part is handled at the API Gateway level using Spring Security and Keycloak as Identity Provider. All user management can be delegated to Keycloak. In this way, it’s possible to not persist Users on the application and no user information is stored on the application DB.

OIDC Authentication with OAuth2 Authorization Code Flow

As mentioned, it’s possible use OpenID Connect for the authentication part. OpenID Connect 1.0 is an identity layer on top of the OAuth 2.0 protocol which is typically used for the authorization part. In the case of Authorization Code Grant Flow (which is our case), OpenID Connect 1.0 provides a special token called the id_token which is designed to provide an OAuth2 Client with the ability to perform user identity verification and log users in. In certain cases, OAuth2 can be used directly to log users in (as is the case with popular social login providers that do not implement OpenID Connect such as GitHub and Facebook).

Spring Security OAuth 2.0 Login feature lets an application have users log in to the application by using their existing account at an OpenID Connect 1.0 Provider (such as Keycloak). One of the flow of OAuth 2.0 Login is the Authorization Code Grant. The authorization code grant type is used to obtain both Access Tokens and Refresh Tokens and is optimized for confidential clients.

Following is an example of an authentication flow in this scenario

It’s important to notice that, in this scenario, using in particularly Spring Cloud Gateway, once the user has authenticated via Keycloak, it provides tokens for the user, including ID, Access and Refresh tokens, which are JWTs. These are not shared with the frontend, but are stored on the gateway and associated with the user’s session.

When the user logs in via Keycloak, Spring set a Session Cookie (with Spring Cloud Gateway is SESSIONID, not the classic JSESSIONID) on the browser. This session cookie is then sent from the browser to the API gateway for each request (the typical session cookie).

When a request arrives at the gateway with the session cookie, Spring Cloud Gateway is able to retrieve in automatic user’s access token in user’s session and passed — always automatically — to the underlying services. And this is the magic of Spring Cloud Gateway! No JWT token is shared with the frontend. In addition, it can also use the Refresh Token provided by Keycloak to obtain a new Access Token when this one expires, all automatically! By automatically we mean with few lines of configuration.

Of course, as can you imagine, is an example of Stateful authentication.

Authorization and Access Control

As mentioned above, the APIs (endpoints) exposed by the microservices should also be protected. They are generally protected with JWT tokens, in the sense that it is generally only possible to call the APIs of a microservice if a valid JWT token is included in the request, usually with an Authorization Bearer Token Header. In the example application, Keycloak and Spring Security will take care of validating incoming JWT tokens to microservices. As mentioned, in this example the JWT tokens are never shared with the frontend but these can be retrieved automatically by Spring Cloud Gateway and passed to the underlying microservices.

Protect microservices APIs — OAuth2 Resource Server

All APIs of services in our example are protected by JWT Token with OAuth2 protocol. OAuth 2.0 provides a standardized way for applications to secure access to APIs. Services delegate authority management to an Authorization Service (in our case Keycloak). In OAuth2 protocol we have:

• Resource Server: the server hosting the protected resources that the client wants to access. It validates the access token and provides the requested resources if the token is valid;
• Authorization Server: is the component in the OAuth 2.0 protocol which is responsible for managing access rights to protected resources.

With Spring Security, by specifying the authorization server’s issuer-uri of the authorization server (something like follow), the resource server will discover the authorization server’s public keys, and then validate incoming JWTs.

<keycloak_uri>/realms/<realm_id>)

Below is a simple flow example of a request for access to protected resources on a Resource Server:

When a request arrives at the gateway, as explained above, it will retrieve the access token linked to the user’s session and call the API of the underlying services by passing the Authentication Bearer token.
If user’s access token has expired, Spring Security on the gateway retrieve a new Access Token for the user using the Refresh Token provided by Keycloak at authentication time.

RBAC — Role Based Access Controls with Spring Security

Another layer of security that is usually added to applications is one that checks the role of the user who is logged in and making a request. Several application roles are generally defined. Each new user created in the application is assigned one or more roles, and checks are then performed on the endpoints. At the API level, it is defined which user role can call a specific endpoint.

With Keycloak and Spring Security, access tokens are also used by the underlying services for the role-based user authorization part. Roles are defined on Keycloak, assigned to users and included in the access tokens. Roles are used by Spring Security for the authorization part. For example, we can say that a specific endpoint can be called only from user’s that have “Admin” role:

@PreAuthorize("hasRole('ADMIN')")

Validation JWTs

Resource Server will automatically configure itself to validate JWT Bearer Tokens. It achieves this through a deterministic startup process:

• Query the Provider Configuration or Authorization Server Metadata endpoint for the jwks_url property
• Query the jwks_url endpoint for supported algorithms
• Configure the validation strategy to query jwks_url for valid public keys of the algorithms found
• Configure the validation strategy to validate each JWTs iss claim against the one specified in the configuration

Once the application is started up, Resource Server will attempt to process any request containing an Authorization Bearer header:

GET / HTTP/1.1 Authorization: Bearer some-token-value

So long as this scheme is indicated, Resource Server will attempt to process the request according to the Bearer Token specification.

Given a well-formed JWT, Resource Server will:

1. Validate its signature against a public key obtained from the jwks_url endpoint during startup and matched against the JWT
2. Validate the JWT’s exp and nbf timestamps and the JWT’s iss claim
3. Map each scope to an authority with the prefix SCOPE_.

Conclusions

As mentioned, this is only one of many examples that can be given of a microservice architecture. Several other elements are generally present in business applications. What I like most is that I have never seen two identical application. Every time we design a new solution there be always new elements e new things to consider. So the legitimate question to ask when reading this article is: is this the right example to use for my application? And of course the answer is always the same… It depends.

It’s not a comprehensive article that starts with the basics of creating a Spring Boot project and other such things. As title said, we will go straight to the practical implementation of the most important parts, taking some things for granted. You will definitely need a basic understanding of Spring Security.

Spring Security dependency

First thing first: add the Spring Security dependency to your classpath

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

Create Role JPA Entity

For role’s management of a specif user we create a JPA entity:

@Data
@Entity
@Table(name = "roles")
public class Role implements GrantedAuthority {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "role_id")
    private Long id;

    @Column(name = "authority")
    private String authority;
}

Customer Entity: personal and Authentication data

Customer Entity is the model for managing User in our application. In Customer Entity add the implementation of the UserDetails interface (an interface provided by Spring Security) and a field to manage the role(s) of the specific user. This field on the Customer must be related to the Role table with a Many-To-Many relationship:

@Data
@Entity
@Table(name = "customers")
public class Customer implements UserDetails {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id", nullable = false)
    private Long id;

    @Column(name = "password", nullable = false, length = 255)
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
    private String password;

    @ManyToMany(fetch = FetchType.EAGER)
    @JoinTable(
            name = "customer_role",
            joinColumns = {@JoinColumn(name = "customer_id")},
            inverseJoinColumns = {@JoinColumn(name = "role_id")}
    )
    private Set<Role> authorities;

    @Column(name = "email", nullable = false, unique = true, length = 100)
    private String email;

    @Column(name = "phone", nullable = true, length = 15)
    private String phone;

    @Column(name = "firstname", nullable = true, length = 45)
    private String firstname;

    @Column(name = "surname", nullable = true, length = 45)
    private String surname;

    // #############################################
    // overrides part for UserDetails implementation
    @Override
    public String getUsername() {
        return getEmail();
    }
    @Override
    public boolean isAccountNonExpired() {
        return true;
    }
    @Override
    public boolean isAccountNonLocked() {
        return true;
    }
    @Override
    public boolean isCredentialsNonExpired() {
        return true;
    }
    @Override
    public boolean isEnabled() {
        return true;
    }

}

Role-Customer Joining table

We let Hibernate and JPA create the joining table for us. We will be responsible for correctly initializing the roles of a new user created by the application.

This are the new two tables:

Some SQL INSERTs to populate the roles table and the customer_role Joining Table

INSERT INTO roles (role_id, authority) VALUES (1, 'ROLE_ADMIN');
INSERT INTO roles (role_id, authority) VALUES (2, 'ROLE_USER');

INSERT INTO customer_role (customer_id, role_id) VALUES (1, 1);
INSERT INTO customer_role (customer_id, role_id) VALUES (1, 2);
INSERT INTO customer_role (customer_id, role_id) VALUES (2, 1);
INSERT INTO customer_role (customer_id, role_id) VALUES (3, 2);

CustomerRepository JPA repository

We need to create a Spring Data JPA repository for managing Customers in which we declare the findByEmail(String email) method used in the next step.

@Repository
public interface CustomerRepository extends JpaRepository<Customer, Long> {
    Optional<Customer> findByEmail(String email);
}

UserDetailService implementation

Create a new Service as follow which is responsible to retrieve user-related data. This Service which implement a Spring Security class (UserDetailService) has one method named loadUserByUsername() which can be overridden to customize the process of finding the user. It is used to load details about the user during authentication.

@Service
@RequiredArgsConstructor
public class UserService implements UserDetailsService {

    private final CustomerRepository customerRepository;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        return customerRepository.findByEmail(username)
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));
    }
}

SecurityConfig class: Spring Security core with Basic Authentication

After the previous steps, we must to create the configuration class that will be the core of the security managed by Spring Security.

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(getOpenedResources()).permitAll()
                        .requestMatchers("*/customers/register").permitAll()
                        .anyRequest().authenticated())
                .httpBasic(Customizer.withDefaults());
        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public AuthenticationManager authenticationManager(UserDetailsService userDetailsService) {
        DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider();
        daoAuthenticationProvider.setUserDetailsService(userDetailsService);
        return new ProviderManager(daoAuthenticationProvider);
    }

    // some opened endpoints without authentication
    private String[] getOpenedResources() {
        return new String[]{
                "/swagger-ui/**",
                "/swagger-resources",
                "/swagger-resources/**",
                "/v3/api-docs",
                "/v3/api-docs/**"
        };
    }
}

Tips

To make your life easier, it is best to define roles with names like this in the DB:
- ROLE_ADMIN
- ROLE_USER

If we don’t put a “ROLE_” prefix, we’ll need some code to manage that, because Spring Security manages roles with prefixes.

Authorization

With everything configured correctly, we can now add Authorization layer of protection on the various endpoints to check the permissions of the connected user based on their role. To do this, simply add @PreAuthorize annotation like this to the various endpoints.

In the snippet above you can also see one way to retrieve current user from session (after of course user is authenticated with user and password):

@GetMapping("/customer")
@PreAuthorize("hasAnyRole('ADMIN', 'USER')")
public ResponseEntity<List<OrderDTO>> getOrdersCustomer() {
  // one way to get the current Customer from session
  Customer currentCustomer = (Customer) SecurityContextHolder.getContext().getAuthentication().getPrincipal();
  Long idCustomer = currentCustomer.getId();
  List<OrderDTO> orders = orderService.getOrdersCustomer(idCustomer);
  return new ResponseEntity<>(orders, HttpStatus.OK);
}

An even simpler way to get the user in session is to add @AuthenticationPrincipal as a method parameter:

public ResponseEntity<List<OrderDTO>> getOrdersCustomer(@AuthenticationPrincipal Customer customer) {

Authentication

If everything went well, from now on, every time you try to call any API from your browser for the first time you should see a popup requesting the username (email in our case) and password pair. By entering the correct credentials you will log into the application and from this moment the user session will be established:

Authentication with Postman

If you use Postman to test your API, for call any endpoints you should add the Authentication simply going in Authorization tab, click on Basic Auth and put the right credentials:

Bonus

As a bonus (let’s say bonus because it is not strictly related to the topics of the article) I will show you an example of a way to create a Customer with roles:

public record CustomerRegistrationDTO(
        String email,
        String password,
        String firstname,
        String surname,
        String phone,
        boolean isUserAdmin
) {}

@PostMapping("/register")
public Customer registerCustomer(@RequestBody CustomerRegistrationDTO customerRegistrationDTO) {
  return authenticationService.registerCustomer(customerRegistrationDTO);
}

@Service
@Transactional
@RequiredArgsConstructor
public class AuthenticationService {

    private final CustomerRepository customerRepository;
    private final RoleRepository roleRepository;
    private final PasswordEncoder passwordEncoder;

    public Customer registerCustomer(CustomerRegistrationDTO customerRegistrationDTO) {
        String role = Boolean.TRUE.equals(customerRegistrationDTO.isUserAdmin()) ? "ROLE_ADMIN" : "ROLE_USER";
        Role userRole = roleRepository.findByAuthority(role).orElseThrow(() -> new NoSuchElementException("Authority not present"));

        Set<Role> authorities = new HashSet<>();
        authorities.add(userRole);

        Customer newCustomer = new Customer();
        newCustomer.setEmail(customerRegistrationDTO.email());
        newCustomer.setPassword(passwordEncoder.encode(customerRegistrationDTO.password()));
        newCustomer.setAuthorities(authorities);
        newCustomer.setFirstname(customerRegistrationDTO.firstname());
        newCustomer.setSurname(customerRegistrationDTO.surname());
        newCustomer.setPhone(customerRegistrationDTO.phone());

        return customerRepository.save(newCustomer);
    }
}

This is a very simple guide to Basic Authentication (probably the easiest type of Authentication to integrate on Spring Security but also one of the least secure) with Spring Security and Role-Based Authorization. In a real world scenario probably you don’t want to use this type of authentication.