How the bearer token sent to the Integration APIs (/api/integration/**) is validated, and how to configure, replace or disable the validation.
1. Overview
Two mechanisms can validate the token. Exactly one of them should be responsible for a given deployment.
|
Mechanism |
Where it runs |
Validates the token by |
|---|---|---|
|
Spring Security |
Standalone mode only ( |
Verifying the Cognito JWT ( |
|
Private API token validation filter |
Any deployment mode (standalone, Foundation, or a project using the |
Calling a Foundation private API with the token: 2xx = valid |
The private API validation is a plain servlet filter (BearerTokenValidationFilter). It does not need Spring Security, so it also works with Foundation.
2. Defaults per runtime
|
Runtime |
|
Who validates the token |
|---|---|---|
|
Standalone mode ( |
|
Spring Security (Cognito JWT) |
|
Foundation ( |
|
The private API filter |
|
|
|
The private API filter (projects that include |
3. When to use the private API validation in standalone mode
Use it when the token cannot be validated against Cognito. In that case:
-
Disable the Spring Security protection of the integration paths by making them public in the webhook chain of
connector.security:YAMLconnector: security: webhook: enabled: true paths: - /api/integration/**The webhook chain is
permit-all, so Spring Security no longer checks the token on these paths. -
Turn the private API validation on:
YAMLintegration-api: security: token-validation: enabled: true
The filter runs right after the Spring Security filter chain, so it also applies to the paths the webhook chain leaves public.
Never make the paths public in the webhook chain without enabling the validation, otherwise the integration APIs are unprotected.
4. Configuration
Every property can be set as a Spring property or as a Foundation setup property (setup.properties) with the integrationlayer. prefix. If both are present, the Foundation setup property wins.
|
Property |
Default |
Description |
|---|---|---|
|
|
see section 2 |
Registers the validation filter. |
|
|
|
Ant-style patterns, relative to the application context path, on which a bearer token is required. |
|
|
|
Private API called to validate the token. Either a path relative to the private API base URL, or an absolute URL. |
|
|
|
HTTP method used to call the URL. |
|
|
|
Maximum time to wait for the private API answer. |
About the URL. A relative URL is resolved against the private API base URL (PRIVATE_API_BASEURL / integration-api.private.base-url), which normally already ends with /api. Write /configurations/identity/r2/users/self, not /api/configurations/identity/r2/users/self. An absolute URL ignores the base URL and must be written in full.
Spring (application.yml)
integration-api:
security:
token-validation:
enabled: true
paths: [ /api/integration/** ]
url: /configurations/identity/r2/users/self
method: GET
timeout: 3s
Foundation (setup.properties)
integrationlayer.integration-api.security.token-validation.enabled=true
integrationlayer.integration-api.security.token-validation.paths=/api/integration/**
integrationlayer.integration-api.security.token-validation.url=/configurations/identity/r2/users/self
integrationlayer.integration-api.security.token-validation.method=GET
integrationlayer.integration-api.security.token-validation.timeout=10s
${env:...} and ${sys:...} lookups in setup properties are resolved at startup; lookups that need Foundation beans (e.g. ${awsSecret:...}) are not.
5. Validation flow and responses
-
The request path is matched against
paths(relative to the context path). Other paths are not touched. -
The
Authorization: Bearer <token>header is read (the scheme is case-insensitive). -
The configured private API is called with the same
Authorization: Bearer <token>header. The response body is ignored.
|
Situation |
Response |
|---|---|
|
Missing, blank or non-Bearer |
|
|
Private API answers 2xx |
The request continues |
|
Private API answers 401 or 403 |
|
|
Any other status, timeout or connection error |
|
A 503 means the validation service itself failed, not that the token is invalid: clients can safely retry.
6. Custom validation
To validate the token in a different way, declare a BearerTokenValidator bean. It replaces the default private API implementation (the url, method and timeout properties are then ignored; enabled and paths still apply).
@Configuration
class MyTokenValidationConfig {
@Bean
BearerTokenValidator bearerTokenValidator(MyTokenService tokenService) {
return token -> tokenService.isValid(token);
}
}
Contract (BearerTokenValidator#isValid(String token)):
-
return
true→ valid, the request continues; -
return
false→ invalid, the client receives401; -
throw
BearerTokenValidationUnavailableExceptionwhen no verdict can be given → the client receives503.
7. Disabling the validation
Set integration-api.security.token-validation.enabled=false (or the integrationlayer. equivalent). The Foundation setup property takes precedence over the Spring one.
If enabled is true and url is explicitly blank, startup fails unless a custom BearerTokenValidator bean is declared.
8. Troubleshooting
|
Symptom |
Likely cause |
|---|---|
|
Always |
Wrong |
|
Always |
Private API unreachable, timeout too short, or the URL resolves to a wrong path (e.g. a duplicated |
|
Calls without a token are accepted in standalone mode |
The webhook chain makes the paths public and |
|
Tests return |
The test profile sends a token but the private API mock has no mapping for the validation URL: disable the validation in the test profile or stub the URL. |
|
Setting has no effect on Foundation |
Check the |