Authenticating Services in a Microservices Environment

Why this problem is easy to underestimate

When we start building microservices, the first security question usually sounds simple:

“Can we protect this API?”

The first answer is also usually simple. Put a gateway in front of the services. Add Keycloak or another identity provider. Validate the token at the gateway. Route the request to the downstream service.

That setup is useful, but it is not the complete answer.

The real question is:

“Can every service trust the request it has received, understand who or what is calling it, and decide whether that caller should be allowed to perform this action?”

That question changes the architecture.

I originally treated this topic like a setup tutorial: create Eureka, create a gateway, add Keycloak, create one public API and one protected API, then test with curl. It proved that authentication worked, but it did not explain the design decisions properly. This rewrite is closer to how I would discuss the same topic in a real implementation review.

The reference architecture

The basic building blocks are still familiar:

1. Identity provider - Keycloak, Okta, Azure AD, Auth0, Cognito, or another OpenID Connect provider.
2. API gateway - the public entry point for routing, coarse authorization, throttling, and request normalization.
3. Discovery or service registry - useful for routing and resilience, but not a security boundary.
4. Downstream services - accounts, payments, customer profile, limits, notifications, calculators, and other business services.
5. Observability layer - audit logs, traces, correlation IDs, metrics, and alerts.

The important point is this:

The gateway is an enforcement point. It should not become the only enforcement point.

In a small internal system, gateway-only authorization may look acceptable for a while. In a banking, fintech, or enterprise environment, it becomes risky quickly. Services get reused. New channels appear. Batch jobs and schedulers start calling APIs. Partner integrations arrive. Someone exposes an internal route by mistake. If the downstream service blindly trusts the network, the blast radius becomes bigger than expected.

Gateway responsibility versus service responsibility

I like to split the responsibility this way:

This separation keeps the system understandable. The gateway can reject obvious bad requests early. The service still protects the business action.

For example:

1. The gateway can decide that /accounts/** requires an authenticated caller with accounts.read.
2. The accounts service must still decide whether this user can read this specific account.
3. The payments service must still decide whether a payment requires step-up authentication, maker-checker approval, velocity checks, or fraud review.
4. The customer profile service must still decide which fields are visible for a role, purpose, and consent state.

The request flow

A normal external request looks like this:

GET /accounts/123456/transactions?from=2024-07-01
Authorization: Bearer <access-token>
X-Correlation-Id: 7e9c2f0d

The gateway should perform coarse checks:

1. Is the token present?
2. Is the token signature valid?
3. Is the issuer trusted?
4. Has the token expired?
5. Is the token intended for this API audience?
6. Does the token have the route-level scope?
7. Is the caller within rate and abuse limits?

If these checks pass, the request can move forward. That does not mean the business action is automatically allowed.

The downstream service should then perform business checks:

1. Does the caller have access to account 123456?
2. Is the caller acting as a customer, employee, partner, or system?
3. Is the requested action allowed for this role?
4. Is there a consent, purpose, region, or data classification rule?
5. Does the service need step-up authentication?
6. Should this action be audited?

This is the difference between authentication and authorization. Authentication tells us who or what is calling. Authorization decides whether the caller can perform the action.

Using Keycloak as the identity provider

Keycloak is a good local and self-hosted option for this kind of setup. In production, the same architecture applies even if the identity provider is different.

For a Spring Boot resource server, the cleanest configuration is usually to point the application to the issuer:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/realms/bank

With this approach, Spring Security can use the provider metadata and JWKS endpoint to validate JWT signatures and token claims. The application should not hard-code public keys unless there is a strong reason. Let the platform handle key rotation.

For local Keycloak development, the issuer may look like this:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8082/realms/customers

That is fine for local development. Production should use HTTPS, proper realm/client configuration, managed secrets, and stricter token lifetimes.

Gateway security configuration

A simplified Spring Cloud Gateway security configuration can look like this:

package com.mk.gateway.configs;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {

    @Bean
    SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
        return http
                .csrf(ServerHttpSecurity.CsrfSpec::disable)
                .authorizeExchange(exchanges -> exchanges
                        .pathMatchers("/actuator/health").permitAll()
                        .pathMatchers(HttpMethod.POST, "/calculator/fd/interest/public").permitAll()
                        .pathMatchers("/accounts/**").hasAuthority("SCOPE_accounts.read")
                        .pathMatchers("/payments/**").hasAuthority("SCOPE_payments.write")
                        .anyExchange().authenticated()
                )
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults()))
                .build();
    }
}

This is intentionally boring. Boring security configuration is usually better than clever security configuration.

The gateway should reject requests that are clearly not allowed. But I would not put all business rules here. The gateway does not know enough about account ownership, transaction state, consent, purpose, and product rules.

Service-level authorization

The accounts service should not only rely on the gateway. It should also run as a resource server and protect its own endpoints.

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/realms/bank

Then the service can enforce coarse method-level rules:

package com.mk.accounts.controller;

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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/accounts")
public class AccountController {

    @GetMapping("/{accountId}/transactions")
    @PreAuthorize("hasAuthority('SCOPE_accounts.read')")
    public TransactionSummary getTransactions(@PathVariable String accountId) {
        return accountService.getTransactionsForAllowedCaller(accountId);
    }
}

The important part is hidden inside getTransactionsForAllowedCaller. That is where the service checks whether the caller can read this particular account.

Scope checks are not enough for many real systems. A user may have accounts.read, but that does not mean the user can read every account. The service needs resource-level authorization.

Service-to-service calls

User-facing calls are not the only calls in a microservices system. Services also call each other.

For example:

1. The payments service calls the limits service.
2. The statement service calls the accounts service.
3. The customer service calls the consent service.
4. A scheduler calls the notification service.

For these cases, avoid passing usernames and passwords around. Also avoid using the OAuth resource owner password grant for modern applications. It exposes user credentials to the client and does not fit well with MFA or modern authentication flows.

For machine-to-machine calls, use one of these patterns:

1. Client credentials - the calling service gets a token as itself.
2. mTLS - the calling service proves its identity with a client certificate.
3. Private key JWT - the service authenticates to the token endpoint using asymmetric keys.
4. Workload identity - common in Kubernetes and cloud-native platforms.

A client credentials request looks like this:

POST /realms/bank/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id=statement-service
client_secret=${STATEMENT_SERVICE_SECRET}
grant_type=client_credentials
scope=accounts.read

The service receiving this call should know that the caller is statement-service, not Mohit, not a random user, and not just “internal traffic”.

That distinction matters. A user token represents a user. A service token represents a service. Mixing them casually creates audit and authorization problems.

Propagating user context

Sometimes a downstream service needs to know the end user behind the request. There are multiple ways to do this:

1. Forward the original access token.
2. Exchange the external token for an internal token.
3. Create a signed internal identity context at the edge.
4. Use a service mesh or identity-aware proxy pattern.

Forwarding the original access token is simple, but it is not always the best design. It increases the number of services that need to understand external tokens and increases the impact if that token leaks.

For larger systems, I prefer creating an internal representation of the caller after the edge has validated the external token. That internal representation should be signed, short-lived, and never exposed back to the browser or external client.

The internal context may include:

{
  "subject": "user-78231",
  "actorType": "customer",
  "channel": "mobile",
  "roles": ["retail_customer"],
  "scopes": ["accounts.read"],
  "purpose": "self_service",
  "correlationId": "7e9c2f0d"
}

Do not pass identity as plain headers such as X-User-Id unless every receiving service can cryptographically verify who created that header. Plain headers are too easy to spoof when a service is accidentally exposed or when an internal caller is compromised.

Public APIs are not unmanaged APIs

In the old version of this post, I used a fixed deposit calculator as the public API. That example is still useful.

A public endpoint may not need login:

POST /calculator/fd/interest/public
Content-Type: application/json

{
  "schemeCode": "SCHEME_A",
  "amount": 20000,
  "durationInMonths": 12
}

But “public” does not mean “unprotected”.

Public APIs still need:

1. Input validation
2. Rate limiting
3. Abuse detection
4. Request size limits
5. Bot controls where needed
6. Logging and correlation IDs
7. A clear decision on whether the result can be cached

Many incidents start with public endpoints that were considered harmless.

Token validation checklist

For every service that accepts a bearer token, I check at least the following:

The audience check is worth calling out. I have seen systems validate signature and expiry but ignore audience. That means a token issued for one API may work against another API. In a microservices environment, that is a serious design gap.

What I would avoid

These are the patterns I would avoid in a production setup:

1. Validating tokens only at the gateway and leaving sensitive services open internally.
2. Passing X-User-Id or X-Role headers without signing or trusted infrastructure controls.
3. Logging full access tokens.
4. Storing client secrets in application.yml.
5. Using the resource owner password grant for user login.
6. Treating service discovery as a security mechanism.
7. Giving one broad scope such as api.access to every client.
8. Using long-lived access tokens because refresh logic is inconvenient.
9. Mixing user tokens and service tokens without an audit model.
10. Relying on network location as the proof of identity.

Each of these choices may look convenient during development. Most of them become expensive later.

A practical delivery sequence

If I had to implement this in phases, I would do it like this:

1. Set up the identity provider and define realms, clients, scopes, roles, and token lifetimes.
2. Configure the gateway as a resource server and reject unauthenticated traffic by default.
3. Mark public routes explicitly. Everything else should require authentication.
4. Add route-level scope checks at the gateway.
5. Configure sensitive downstream services as resource servers too.
6. Add resource-level authorization inside the business services.
7. Add service-to-service authentication using client credentials, mTLS, or workload identity.
8. Add correlation IDs, audit events, and authorization decision logs.
9. Review token contents and remove claims that do not need to travel.
10. Run negative tests: wrong issuer, wrong audience, expired token, missing scope, spoofed header, direct service access.

The negative tests are important. Security is not proven by one happy curl command. It is proven when the wrong requests fail for the right reasons.

Final thought

The gateway is a good place to start, but it is not where the security design ends.

In a microservices system, every service is a small boundary. The service should understand the caller, validate the trust material it receives, and enforce the rules that belong to its own domain.

That is the difference between “we added authentication” and “the system is designed to survive real usage”.

References I keep handy

1. OAuth 2.0 Security Best Current Practice, RFC 9700
2. OWASP Microservices Security Cheat Sheet
3. Spring Security OAuth2 Resource Server JWT documentation
4. Keycloak OpenID Connect endpoints documentation