From 15a4f9d4604f315c696e3b572bc3ec2fea92a010 Mon Sep 17 00:00:00 2001 From: NopeCharon <115794254+NopeCharon@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:52:09 +0000 Subject: [PATCH] docs(core): fix the JWT source examples and document CachedJwtSource The JWT Source section of the core README showed code that does not compile against the current API: it created sources with JwtSource.newSource(), but JwtSource is an interface without static methods (the factories are DefaultJwtSource.newSource and CachedJwtSource.newSource), used a nested JwtSource.JwtSourceOptions class, while the options are the top-level JwtSourceOptions class, and looked up bundles with TrustDomain.of, which does not exist. Both timeout sections also pointed to a newSource(Duration timeout) method that does not exist. - Use DefaultJwtSource.newSource, JwtSourceOptions and TrustDomain.parse in the examples. - Show how to set the initialization timeout with the initTimeout option of X509SourceOptions and JwtSourceOptions, and explain that the spiffe.newX509Source.timeout and spiffe.newJwtSource.timeout System properties are only a fallback, are read when the source class is loaded, and that newSource throws X509SourceException or JwtSourceException when the timeout expires. - Document CachedJwtSource, which was not mentioned anywhere: it caches JWT-SVIDs per subject and audiences and refreshes them after half of their lifetime, while DefaultJwtSource fetches a new one on every call. - Document validating JWT-SVIDs received from other workloads with JwtSvid.parseAndValidate and a JwtSource, including the exceptions it throws. All the examples compile against the current core module. Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com> --- CHANGELOG.md | 1 + java-spiffe-core/README.md | 85 ++++++++++++++++++++++++++++++++------ 2 files changed, 73 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b71e0f97..57bdc1b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ ### Documentation * Document `SpiffeProvider.install()` in the provider README, and explain that the JDK loads the providers declared in `java.security` with the system class loader, so a provider packaged inside an application archive, such as a Spring Boot executable jar, must be installed programmatically +* Fix the JWT source examples in the core README, which called methods and classes that don't exist, document how to configure the source initialization timeouts with `initTimeout`, and document `CachedJwtSource` and JWT-SVID validation with `JwtSvid.parseAndValidate` ## [0.8.17] - 2026-04-20 diff --git a/java-spiffe-core/README.md b/java-spiffe-core/README.md index db866ab7..38701224 100644 --- a/java-spiffe-core/README.md +++ b/java-spiffe-core/README.md @@ -20,7 +20,7 @@ To create a new X.509 Source: } X509Svid svid = x509Source.getX509Svid(); - X509Bundle bundle = x509Source.getBundleForTrustDomain(TrustDomain.of("example.org")); + X509Bundle bundle = x509Source.getBundleForTrustDomain(TrustDomain.parse("example.org")); ``` The `newSource()` method blocks until the X.509 materials can be retrieved from the Workload API and the `X509Source` is @@ -49,12 +49,26 @@ The `X509Source newSource()` method blocks waiting until an X.509 context is fet using an exponential backoff policy with this progression of delays between retries: 1 second, 2 seconds, 4, 8, 16, 32, 60, 60, 60... It retries indefinitely unless a timeout is configured. -This timeout can be configured either providing it through the `newSource(Duration timeout)` method or -using a System property: +This timeout can be configured either with the `initTimeout` option of the `X509SourceOptions` passed to the +`newSource(X509SourceOptions options)` method: -`spiffe.newX509Source.timeout=PT30S` +``` + DefaultX509Source.X509SourceOptions x509SourceOptions = DefaultX509Source.X509SourceOptions + .builder() + .initTimeout(Duration.ofSeconds(30)) + .build(); + + X509Source x509Source = DefaultX509Source.newSource(x509SourceOptions); +``` + +or with a System property, which is used when the options don't set an `initTimeout`: -The `timeout` duration is expressed in `ISO-8601` format. +`-Dspiffe.newX509Source.timeout=PT30S` + +The System property is expressed in `ISO-8601` format. It is read once, when the `DefaultX509Source` class is +loaded, so it has to be set before then, for example on the `java` command line. + +If the X.509 context cannot be fetched before the timeout expires, `newSource` throws an `X509SourceException`. ## JWT Source @@ -66,14 +80,14 @@ To create a new JWT Source: ``` JwtSource jwtSource; try { - jwtSource = JwtSource.newSource(); + jwtSource = DefaultJwtSource.newSource(); } catch (SocketEndpointAddressException | JwtSourceException e) { // handle exception } JwtSvid svid = jwtSource.fetchJwtSvid(SpiffeId.parse("spiffe://example.org/test"), "testaudience1", "audience2"); - JwtBundle bundle = jwtSource.getBundleForTrustDomain(TrustDomain.of("example.org")); + JwtBundle bundle = jwtSource.getBundleForTrustDomain(TrustDomain.parse("example.org")); ``` The `newSource()` method blocks until the JWT materials can be retrieved from the Workload API and the `JwtSource` is @@ -86,26 +100,71 @@ The socket endpoint address is configured through the environment variable `SPIF Another way to configure it is by providing an `JwtSourceOptions` instance to the `newSource` method: ``` - JwtSource.JwtSourceOptions jwtSourceOptions = JwtSource.JwtSourceOptions + JwtSourceOptions jwtSourceOptions = JwtSourceOptions .builder() .spiffeSocketPath("unix:/tmp/agent-other.sock") .build(); - JwtSource jwtSource = JwtSource.newSource(jwtSourceOptions); + JwtSource jwtSource = DefaultJwtSource.newSource(jwtSourceOptions); +``` + +### Cache JWT-SVIDs + +`DefaultJwtSource` fetches a new JWT-SVID from the Workload API on every `fetchJwtSvid` and `fetchJwtSvids` call. +To reuse JWT-SVIDs, create the source with `CachedJwtSource` instead, which has the same `newSource` methods and +options: + +``` + JwtSource jwtSource = CachedJwtSource.newSource(); ``` +It caches the JWT-SVIDs per subject SPIFFE ID and set of audiences, and fetches new ones from the Workload API once +the cached JWT-SVIDs have passed half of their lifetime. + ### Configure a timeout for JwtSource initialization The `JwtSource newSource()` method blocks until the JWT materials are fetched. The fetching process is retried using an exponential backoff policy with this progression of delays between retries: 1 second, 2 seconds, 4, 8, 16, 32, 60, 60, 60... It retries indefinitely unless a timeout is configured. -This timeout can be configured either providing it through the `newSource(Duration timeout)` method or -using a System property: +This timeout can be configured either with the `initTimeout` option of the `JwtSourceOptions` passed to the +`newSource(JwtSourceOptions options)` method: + +``` + JwtSourceOptions jwtSourceOptions = JwtSourceOptions + .builder() + .initTimeout(Duration.ofSeconds(30)) + .build(); + + JwtSource jwtSource = DefaultJwtSource.newSource(jwtSourceOptions); +``` + +or with a System property, which is used when the options don't set an `initTimeout`: -`spiffe.newJwtSource.timeout=PT30S` +`-Dspiffe.newJwtSource.timeout=PT30S` + +The System property is expressed in `ISO-8601` format. It is read once, when the `DefaultJwtSource` or +`CachedJwtSource` class is loaded, so it has to be set before then, for example on the `java` command line. + +If the JWT bundles cannot be fetched before the timeout expires, `newSource` throws a `JwtSourceException`. + +## Validate JWT-SVIDs + +A `JwtSource` is also a source of JWT bundles, so it can be used to validate the JWT-SVIDs received from other +workloads. `JwtSvid.parseAndValidate` verifies the token signature with the JWT authorities of the trust domain of +the token's subject, and checks that the token has not expired and that its `aud` claim contains all the expected +audiences: + +``` + JwtSvid svid = JwtSvid.parseAndValidate(token, jwtSource, Collections.singleton("audience1")); + SpiffeId peerSpiffeId = svid.getSpiffeId(); +``` -The `timeout` duration is expressed in `ISO-8601` format. +It throws a `JwtSvidException` if the token is not a valid JWT-SVID, has expired, has an invalid signature or its +`aud` claim does not contain the expected audiences, a `BundleNotFoundException` if there is no JWT bundle for the +trust domain of the subject, and an `AuthorityNotFoundException` if the bundle has no JWT authority with the key ID +of the token. `JwtSvid.parseInsecure` parses and checks a token like `parseAndValidate`, but without verifying its +signature. ## Marshal X.509-SVIDs