SPIFFE Client
experimentalSPIFFE (Secure Production Identity Framework for Everyone) provides cryptographic workload identities in zero-trust environments. The SPIFFE client extension uses the Workload API to retrieve JWT Verifiable Identity Documents (JWT-SVIDs) for Quarkus workloads directly from the local SPIRE Agent. It simplifies deployment by eliminating the need for a SPIFFE client sidecar that stores JWT-SVIDs on a mounted file path for Quarkus to read.
|
This technology is considered experimental. In experimental mode, early feedback is requested to mature the idea. There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker. For a full list of possible statuses, check our FAQ entry. |
Adding the extension
Add the quarkus-spiffe-client extension to your project:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-spiffe-client</artifactId>
</dependency>implementation("io.quarkus:quarkus-spiffe-client")Configuration
The extension requires the URI of the SPIRE Agent’s Workload Endpoint socket:
quarkus.spiffe-client.endpoint-socket=unix:///run/spire/sockets/agent.sockIf quarkus.spiffe-client.endpoint-socket is not set, the extension falls back to the standard SPIFFE_ENDPOINT_SOCKET environment variable as defined by the SPIFFE Workload Endpoint specification.
This environment variable is typically set by the SPIRE Agent for workloads it manages.
The URI must use one of the following schemes, as defined by the SPIFFE Workload Endpoint specification:
-
unix://for Unix Domain Sockets (production default), for exampleunix:///run/spire/sockets/agent.sock -
tcp://for TCP connections (development and testing), for exampletcp://127.0.0.1:8080
For the tcp scheme, the host must be an IP address and a port is required.
Hostnames are not accepted.
On Windows, only the tcp:// scheme is currently supported.
Retrieve JWT-SVID
Inject the SpiffeClient CDI bean to retrieve JWT-SVIDs from the SPIRE Agent.
The following example retrieves a single JWT-SVID for one audience:
import io.quarkus.spiffe.client.WorkloadJsonWebToken;
import io.quarkus.spiffe.client.SpiffeClient;
@ApplicationScoped
public class MyService {
@Inject
SpiffeClient spiffeClient;
public Uni<String> getToken() {
return spiffeClient.getWorkloadJsonWebToken("https://my-audience")
.map(WorkloadJsonWebToken::token);
}
}To specify multiple audiences:
import java.util.Set;
import io.quarkus.spiffe.client.WorkloadJsonWebToken;
import io.quarkus.spiffe.client.SpiffeClient;
import io.smallrye.mutiny.Uni;
public Uni<String> getWorkloadIdentity() {
return spiffeClient.getWorkloadJsonWebToken(Set.of("https://audience-a", "https://audience-b"))
.map(WorkloadJsonWebToken::subject); (1)
}| 1 | The subject() method returns the JWT sub claim, which is a valid SPIFFE ID, for example spiffe://example.org/myservice. |
Calls are not retried automatically; implement your own retry logic if your use case requires it.
Default audiences
Pre-configure default audiences with quarkus.spiffe-client.audiences so callers do not need to specify them on every request:
quarkus.spiffe-client.audiences=https://keycloak.example.com,https://mcp-server.example.comreturn spiffeClient.getWorkloadJsonWebToken().map(WorkloadJsonWebToken::token);When explicit audiences are provided, they take precedence over the configured defaults:
return spiffeClient.getWorkloadJsonWebToken("https://other-service.example.com").map(WorkloadJsonWebToken::token);Testing
In dev and test modes, the extension provides a Dev Service that emulates the SPIFFE Workload API with a pre-configured identity and a locally generated key pair.
While it does not support custom authorization policies or registration entries, it is sufficient for verifying that your application correctly retrieves and uses JWT-SVIDs without requiring external SPIRE infrastructure.
You can choose the transport protocol with the quarkus.spiffe-client.devservices.transport property, which accepts unix (default) or tcp.
OIDC SPIFFE Client Authentication
When combined with quarkus-oidc or quarkus-oidc-client, this extension can supply JWT-SVIDs as client assertions automatically:
-
To authenticate the OIDC provider client during the authorization code exchange, see the OIDC provider client authentication section of the OIDC code flow guide.
-
To authenticate an
OidcClientforclient_credentialsor other grant types, see the OidcClient authentication section of the OIDC client reference.
Extension integration
Extensions integrating with SpiffeClient should depend on the API module:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-spiffe-client-api</artifactId>
</dependency>Configuration reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
If SPIFFE Workload API client is enabled. Environment variable: Show more |
boolean |
|
Flag to enable (default) or disable Dev Services. Environment variable: Show more |
boolean |
|
Transport protocol for the SPIFFE Workload API server. Environment variable: Show more |
|
|
SPIFFE Workload Endpoint socket URI. Supports If not set, the standard Example values: Environment variable: Show more |
|
|
Default audience values that a SPIFFE JSON Web Token (JWT-SVID) is required to contain in its audience Environment variable: Show more |
list of string |
