When a single business operation spans several microservices, the caller's identity must travel with it. Without it, the downstream services cannot authorize the work, and the audit trail of who initiated the operation is lost. This blog walks through a Quarkus quickstart that carries a JSON Web Token (JWT) through a MicroProfile LRA saga using the @PropagateToken annotation, and then examines where that propagation ends and explicit configuration takes over.
You can find the runnable code in the quickstart module rts/lra-examples/lra-jwt/quarkus/token-propagation.
The two specifications
MicroProfile LRA coordinates distributed transactions with the saga pattern. Instead of holding database locks across services, each participant does its work immediately and registers a compensation to undo it. A coordinator drives the participants to either @Complete (on success) or @Compensate (on failure). This works across plain HTTP, so it suits microservices far better than classic two-phase commit.
MicroProfile JWT turns a signed bearer token into an authenticated identity. Inject JsonWebToken and you obtain the caller's subject and issuer. The signature makes the token tamper-proof; the runtime verifies it against the issuer's public key (a JWKS).
Combining them raises a practical question: how does the token reach the inventory service, the payment service, and the coordinator?
Environment setup
Clone and build lra:
git clone https://github.com/jbosstm/lra.git cd lra mvn clean install -DskipTests cd ..
Clone and build the quickstart:
git clone https://github.com/marcosgopen/quickstart -b lra-jwt cd quickstart mvn clean install -DskipTests cd rts/lra-examples/lra-jwt/quarkus/token-propagation
The scenario
┌────────────────┐ reserve / release
Client ──Bearer JWT──► │ OrderService │ ─────────────────► InventoryService
│ @LRA(REQUIRED) │ process / refund
│ @PropagateToken │ ─────────────────► PaymentService
└─────────────────┘
OrderService opens an LRA and calls two participants. If the payment is declined, the whole order is rolled back and the inventory reservation is compensated.
The forward path: @PropagateToken
The orchestrator method is concise:
@POST
@Path("/create")
@Authenticated
@LRA(LRA.Type.REQUIRED)
@PropagateToken
public Response createOrder(OrderRequest order,
@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
@HeaderParam(HttpHeaders.AUTHORIZATION) String authHeader,
@Context UriInfo uriInfo) {
// ... calls inventory then payment, forwarding authHeader on each hop
}
@PropagateToken — introduced with the JWT integration in LRA 2.0.0.Final — propagates the caller's identity on outbound calls. It works as follows:
- The LRA server filter (
ServerLRAFilter) reads the inboundAuthorization: Bearer <jwt>header, confirms it is a well-formed JWT, and stores it in a thread-local for the request. - Every LRA-protocol call the service makes to the coordinator — starting the LRA, enlisting a participant, closing or cancelling it — passes through the LRA client request filter, which reads that thread-local (or a CDI-injected
JsonWebToken, or a configured client property) and re-attachesAuthorization: Bearer <jwt>. - The service-to-service calls forward the same header explicitly, so each participant receives the token, verifies it, and repeats the process when it enlists.
The result is visible in the logs: the inventory and payment endpoints inject the token and record the authenticated caller:
Reserving 2 x ITEM-123 for order ORDER-001 ... (caller=demo-user, authHeader=present) Processing payment of 99.99 for order ORDER-001 ... (caller=demo-user, authHeader=present)
Identity on the callback path
The callback path works differently from the forward path. The coordinator does not persist the end user's token and replay it on the @Complete/@Compensate callbacks. It attaches a token only when it has been configured to, and the token it then sends is one of:
- a request-scoped token, when a close/cancel is driven by an inbound request that the coordinator itself authenticates, or
- a pre-provisioned service token, used by recovery — the background threads that finish interrupted sagas, where no inbound user request exists at all.
That second case is the real reason a stored user token wouldn't work anyway: a long-running action might not complete until minutes, hours, or days later, by which point the user's short-lived access token has long expired. Recovery needs its own durable credential.
In this quickstart the standalone coordinator is not configured with outbound auth providers or a service token, so the callbacks arrive with no Authorization header, as the logs confirm:
Complete callback for LRA ... (caller=null, authHeader=absent): committed ITEM-123
This is the observable default, and it marks the boundary between the two halves of the story: forward propagation requires no configuration, whereas authenticated callbacks require coordinator configuration and a shared identity provider. The next section configures them — see Authenticating the callbacks.
Watching a compensation
Send an order with a negative amount and the payment declines (HTTP 402). OrderService turns that into a failure, the LRA is cancelled, and the reservation that already joined is released:
Reserving 1 x ITEM-123 for order ORDER-002 ... (caller=demo-user, authHeader=present) Payment declined for order ORDER-002 (negative amount) Compensate callback for LRA ... (caller=null, authHeader=absent): released ITEM-123
The forward hops are authenticated; the compensation callback is not, following the same rule as above.
Authenticating the callbacks
The section above shows the default: an unconfigured coordinator, with callbacks that carry no token. To complete the picture, use a coordinator configured for authentication. The lra-coordinator-quarkus application provides this — opt-in inbound JWT protection of its own endpoints, an outbound callback filter, and a pluggable service-token provider — and is published as quay.io/jbosstm/lra-coordinator:latest.
Two pieces have to line up:
- The participant enforces authentication on its callback endpoints. This module leaves that disabled by default (so the walkthrough above works without a configured coordinator); enable it by starting the participant with
-Dparticipant.callback.auth.policy=authenticated. The/inventory/compensate,/payment/complete, and related paths then reject any request without a valid token. - The coordinator presents a token on every callback. Run the image with the callback filter enabled and a service token mounted as a secret volume — the classic Kubernetes pattern. The coordinator re-reads the file every
refresh-seconds, so a rotated secret never goes stale:# the coordinator's own identity; in production this comes from your IdP, not the demo endpoint curl -s "http://localhost:8081/auth/token?subject=lra-coordinator" | sed 's/^Bearer //' > ~/lra-secrets/service-token.jwt podman run -d --network host \ -v ~/lra-secrets:/var/run/secrets/lra:ro,Z \ -e LRA_AUTH_POLICY=authenticated \ -e MP_JWT_VERIFY_PUBLICKEY_LOCATION=http://localhost:8081/auth/jwks \ -e MP_JWT_VERIFY_ISSUER=https://demo.narayana.io \ -e LRA_HTTP_CLIENT_PROVIDERS=io.narayana.lra.coordinator.security.JwtTokenCallbackRequestFilter \ -e LRA_SECURITY_SERVICE_TOKEN_LOCATION=/var/run/secrets/lra/service-token.jwt \ quay.io/jbosstm/lra-coordinator:latest
With both sides configured, the callback log shows an authenticated caller, and the token it uses depends on how the callback was driven:
Complete callback for LRA ... (caller=demo-user, authHeader=present): committed ITEM-123 Compensate callback for LRA ... (caller=lra-coordinator, authHeader=present): released ITEM-123
The first ran inline with a close that the coordinator handled on a request thread, so it reused the caller's propagated token. The second was driven by a timeout or recovery on a background thread with no inbound request — the recovery case described in Identity on the callback path — so it fell back to the coordinator's service token (subject=lra-coordinator). This is the purpose of a dedicated service credential: it is available precisely when the user's token is not.
Requiring an authenticated caller
Every forward endpoint in this example — createOrder and the reserve/process participant operations — is annotated @Authenticated, so a request without a valid token is rejected with 401 before any work runs. (@LRA(MANDATORY) only requires an LRA context, not an identity, so the participant methods need @Authenticated as well.) No custom security code is required; authentication is enforced by MicroProfile JWT.
Generating keys
The demo mints its own tokens, so no external identity provider is required to run it. The RSA key pair is generated in memory at start-up — nothing is written to disk or committed to source control — and the public half is published at /auth/jwks, the location that mp.jwt.verify.publickey.location points to. The application therefore verifies the tokens it issues, and the unit tests assert the key properties: a token verifies only against the published key, and the JWKS never exposes private material.
In production, remove JwtKeyGenerator and point mp.jwt.verify.publickey.location at a real provider's JWKS (Keycloak, Entra ID, Auth0, and similar).
Taking it to production
- Real IdP. Replace the in-process key/token generator with an external identity provider.
- HTTPS everywhere. The coordinator URL and every inter-service hop should be TLS.
- Separate credentials for separate jobs. Use short-lived access tokens for the forward path, and give the coordinator a dedicated service token (
lra.security.service-token.location) so recovery-driven callbacks can authenticate long after the user's token has expired. Mount it as a secret volume intoquay.io/jbosstm/lra-coordinator(as shown above) and rotate it with your secrets tooling — the coordinator re-reads it on an interval. - Secure the coordinator's own endpoints too. That is a distinct concern from propagation. The
lra-coordinator-quarkusimage does it withlra.auth.policy=authenticatedplusmp.jwt.verify.*(shown above); the sibling wildfly example shows the WildFly equivalent with endpoint-to-role mappings.
Code: https://github.com/jbosstm/quickstart · LRA: https://github.com/eclipse/microprofile-lra · Narayana LRA: https://github.com/jbosstm/lra · JWT: https://github.com/eclipse/microprofile-jwt-auth · Narayana: https://narayana.io/
