Secure Your Spring Cloud Microservices with OAuth2: A Step‑by‑Step Guide

Preface

Security is the most important aspect when exposing public APIs composed of many microservices. Spring provides useful features and frameworks that simplify security configuration. This article shows how to use Spring Cloud and OAuth2 to provide token‑based security behind an API gateway.

Theoretical Knowledge

OAuth2 is widely used and allows sharing resources via an open‑standard authorization flow. Basic terms include Resource Owner, Resource Server, Authorization Server, Access Token, and Authorization Grant (code, implicit, password, client credentials).

Resource Owner – handles access to resources

Resource Server – stores resources that can be shared with a special token

Authorization Server – manages keys, tokens and grants, ensuring proper access rights

Access Token – key that permits resource access

Authorization Grant – permission to access, with several methods: authorization code, implicit, resource owner password credentials, client credentials

Typical flow: the client requests authorization from the resource owner, receives an authorization grant, exchanges it for an access token from the authorization server, and then uses the token to call the resource server.

Solution

The architecture (shown below) uses Zuul as an API gateway to proxy requests to the authorization server and two account‑service instances. Eureka registers all services.

Gateway

The gateway does not enforce security itself; it simply forwards requests. In Zuul configuration we set sensitiveHeaders to empty to allow the Authorization header to be forwarded.

zuul:
  routes:
    uaa:
      path: /uaa/**
      sensitiveHeaders:
      serviceId: auth-server
    account:
      path: /account/**
      sensitiveHeaders:
      serviceId: account-service

The gateway’s main class enables Zuul proxy and discovery client.

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

Authorization Server

The authorization server uses Spring Security’s default configuration. Client details are stored in an in‑memory repository (client‑id: acme, client‑secret: secret). Configuration snippet:

security:
  user:
    name: root
    password: password
  oauth2:
    client:
      client-id: acme
      client-secret: secret

The main class enables the authorization server, discovery client, and resource server, and defines a REST endpoint that returns the authenticated principal.

@SpringBootApplication
@EnableAuthorizationServer
@EnableDiscoveryClient
@EnableResourceServer
@RestController
public class AuthServer {
    @RequestMapping("/user")
    public Principal user(Principal user) {
        return user;
    }
    public static void main(String[] args) {
        SpringApplication.run(AuthServer.class, args);
    }
}

Account Service

The account microservice exposes a simple @GET endpoint that always returns the same account. It is annotated with discovery and resource‑server support.

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

Client configuration for the resource server:

security:
  oauth2:
    client:
      client-id: acme
      client-secret: secret
    resource:
      loadBalanced: true
      userInfoUri: http://localhost:9999/user

Testing

Use a web browser or a REST client (e.g., Chrome Advanced REST Client) to start the OAuth2 flow:

http://localhost:8765/uaa/oauth/authorize?response_type=token&client_id=acme&redirect_uri=http://example.com&scope=openid&state=48532

After approving, the server redirects to the provided redirect_uri with an access token in the fragment. Use this token as a Bearer token in the Authorization header to call the account endpoint.

Conclusion

The solution demonstrates that Spring Security provides out‑of‑the‑box mechanisms for securing microservices, and its components are easily extensible for more advanced requirements.