Spring Middleware provides explicit client security for Spring Boot microservices.
Declarative @MiddlewareClient proxies can authenticate to downstream services
using OAuth2 client credentials, API keys, or passthrough modes, while keeping outbound
request behavior visible and consistent.
Declarative middleware clients support several outbound security modes so proxy calls can authenticate consistently to downstream services. Configuration can be defined at client level and refined at method level through annotations.
Client security is not the same as service HTTP security. This page describes how a service
authenticates when it calls another service through @MiddlewareClient.
Inbound authentication and authorization are covered separately in the service security guide.
Declarative clients map to a small set of outbound security strategies.
No security is applied to the outbound request.
A header from the incoming request is copied to the downstream call.
An API key header is attached from class-level or per-method configuration.
An access token is obtained through client credentials and attached as a bearer token.
Client-wide configuration typically lives under the client prefix.
The effective behavior is a combination of configuration and proxy annotations.
client:
registry-endpoint: ${REGISTRY_ENDPOINT:http://localhost:8080/registry}
product:
security:
type: OAUTH2_CLIENT_CREDENTIALS
api-key: ${API_KEY_PRODUCT_SERVICE:default-product-api-key}
listProducts:
api-key: ${API_KEY_PRODUCT_SERVICE:default-product-list-api-key}
oauth2:
client-id: ${OAUTH2_CLIENT_ID_PRODUCT_SERVICE:product-service}
client-secret: ${OAUTH2_CLIENT_SECRET_PRODUCT_SERVICE}
token-uri: ${OAUTH2_TOKEN_URI_PRODUCT_SERVICE:http://keycloak:8080/realms/spring-middleware/protocol/openid-connect/token}Configuration defines the default security mode and base credentials for the proxy.
Methods can override class-level API key values or add required OAuth2 scopes when needed.
The runtime analyzer combines configuration and annotations to select the effective security strategy.
The proxy metadata model uses annotations to declare how security should be applied to a client and its methods.
@MiddlewareContract or @MiddlewareClient defines the security type placeholder@MiddlewarePassthrough declares passthrough header behavior@MiddlewareApiKey defines API key header name and value placeholder@MiddlewareClientCredentials defines token endpoint, client id, and secret@MiddlewareApiKeyValue overrides class-level API key value@MiddlewareRequiredScopes declares required OAuth2 scopes for the methodOutbound security is resolved in a small but explicit runtime sequence.
ProxySecurityAnalyzer inspects annotations and resolved placeholders to build a client security configuration.
Method metadata contributes scopes, per-method API keys, or a void configuration when nothing extra is needed.
SecurityManagerApplier delegates to the correct SecurityApplier based on the selected client type.
The selected applier attaches headers, API key values, or bearer tokens to the outbound WebClient call.
The proxy runtime first resolves security metadata, then applies the selected strategy to the request.
Passthrough forwards a header from the incoming request to the outbound request. This is useful when the downstream service should receive the caller's authentication token.
client:
product:
security:
type: PASSTHROUGH@MiddlewareContract(security = "PASSTHROUGH")
@MiddlewarePassthrough(headerName = "Authorization", required = "true")
public interface ProductClient {
@GetMapping("/api/v1/products")
List<ProductDto> listProducts();
}API key mode attaches a configured header to the outbound request. The value can come from a class-level annotation or a method-level override.
@MiddlewareContract(security = "API_KEY")
@MiddlewareApiKey(headerName = "X-API-KEY", value = "${client.product.api-key:}")
public interface ProductClient {
@GetMapping("/api/v1/products")
@MiddlewareApiKeyValue("${client.product.list-api-key:}")
List<ProductDto> listProducts();
}SecurityApiKeyApplier adds the resolved header to the requestClient credentials mode acquires an access token and sends it as a bearer token in the outbound request.
client:
product:
security:
type: OAUTH2_CLIENT_CREDENTIALS
oauth2:
client-id: ${OAUTH2_CLIENT_ID_PRODUCT_SERVICE:product-service}
client-secret: ${OAUTH2_CLIENT_SECRET_PRODUCT_SERVICE}
token-uri: ${OAUTH2_TOKEN_URI_PRODUCT_SERVICE:http://keycloak:8080/realms/spring-middleware/protocol/openid-connect/token}@MiddlewareContract(security = "OAUTH2_CLIENT_CREDENTIALS")
@MiddlewareClientCredentials(
tokenUri = "${client.product.security.oauth2.token-uri}",
clientId = "${client.product.security.oauth2.client-id}",
clientSecret = "${client.product.security.oauth2.client-secret}"
)
public interface ProductClient {
@GetMapping("/api/v1/products")
@MiddlewareRequiredScopes({"products.read"})
List<ProductDto> listProducts();
}The built-in OAuth2 client is responsible for token acquisition and caching.
This keeps outbound authentication efficient and predictable. Services do not need to hand-roll token lifecycle code for each proxy client.
Declarative client security is most effective when secrets remain externalized and method-level overrides are used deliberately.
Use environment variables or a secrets manager for client secrets and API keys.
Override class-level defaults only when different endpoints really need distinct API keys or scopes.
When passthrough headers are required, validate them early so missing caller context does not create ambiguous downstream failures.