Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
85 changes: 72 additions & 13 deletions java-spiffe-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
Loading