Class DefaultWorkloadApiClient

java.lang.Object

io.spiffe.workloadapi.DefaultWorkloadApiClient

All Implemented Interfaces:

WorkloadApiClient, Closeable, AutoCloseable

public final class DefaultWorkloadApiClient
extends Object
implements WorkloadApiClient

Represents a client to interact with the Workload API.

Supports one-shot calls and watch updates for X.509 and JWT SVIDs and bundles.

The watch for updates methods support retries using an exponential backoff policy to reestablish the stream connection to the Workload API.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DefaultWorkloadApiClient.ClientOptions	Options for creating a new DefaultWorkloadApiClient.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this Workload API closing the underlying channel, cancelling the contexts and shutdown the executor service.
JwtBundleSet	fetchJwtBundles()	Fetches the JWT bundles for JWT-SVID validation, keyed by trust domain.
JwtSvid	fetchJwtSvid(@NonNull SpiffeId subject, @NonNull String audience, String... extraAudience)	Fetches a SPIFFE JWT-SVID on one-shot blocking call.
JwtSvid	fetchJwtSvid(@NonNull String audience, String... extraAudience)	Fetches a SPIFFE JWT-SVID on one-shot blocking call.
List<JwtSvid>	fetchJwtSvids(@NonNull SpiffeId subject, @NonNull String audience, String... extraAudience)	Fetches a SPIFFE JWT-SVID on one-shot blocking call.
List<JwtSvid>	fetchJwtSvids(@NonNull String audience, String... extraAudience)	Fetches all SPIFFE JWT-SVIDs on one-shot blocking call.
X509BundleSet	fetchX509Bundles()	Fetches the X.509 bundles on a one-shot blocking call.
X509Context	fetchX509Context()	Fetches an X.509 context on a one-shot blocking call.
static WorkloadApiClient	newClient()	Creates a new Workload API client using the default socket endpoint address.
static WorkloadApiClient	newClient(@NonNull DefaultWorkloadApiClient.ClientOptions options)	Creates a new Workload API client configured with the given client options.
JwtSvid	validateJwtSvid(@NonNull String token, @NonNull String audience)	Validates the JWT-SVID token.
void	watchJwtBundles(@NonNull Watcher<JwtBundleSet> watcher)	Watches for JWT bundles updates.
void	watchX509Bundles(@NonNull Watcher<X509BundleSet> watcher)	Watches for X.509 bundles updates.
void	watchX509Context(@NonNull Watcher<X509Context> watcher)	Watches for X.509 context updates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

newClient

public static WorkloadApiClient newClient()
                                   throws SocketEndpointAddressException

Creates a new Workload API client using the default socket endpoint address. Address.getDefaultAddress()

Returns:

a WorkloadApiClient, the instance concrete type is DefaultWorkloadApiClient

Throws:

SocketEndpointAddressException - if the Workload API socket endpoint address is not valid

newClient

public static WorkloadApiClient newClient(@NonNull
 @NonNull DefaultWorkloadApiClient.ClientOptions options)
                                   throws SocketEndpointAddressException

Creates a new Workload API client configured with the given client options.

If the SPIFFE socket endpoint address is not provided in the options, it uses the default address. Address.getDefaultAddress()

Parameters:

options - DefaultWorkloadApiClient.ClientOptions

Returns:

a WorkloadApiClient, the instance concrete type is DefaultWorkloadApiClient

Throws:

SocketEndpointAddressException - if the Workload API socket endpoint address is not valid

fetchX509Context

public X509Context fetchX509Context()
                             throws X509ContextException

Fetches an X.509 context on a one-shot blocking call.

Specified by:

fetchX509Context in interface WorkloadApiClient

Returns:

an instance of a X509Context containing the X.509 materials fetched from the Workload API

Throws:

X509ContextException - if there is an error fetching or processing the X.509 context

watchX509Context

public void watchX509Context(@NonNull
 @NonNull Watcher<X509Context> watcher)

Watches for X.509 context updates.

A new Stream to the Workload API is opened for each call to this method, so that the client starts getting updates immediately after the Stream is ready and doesn't have to wait until the Workload API dispatches the next update based on the SVIDs TTL.

Specified by:

watchX509Context in interface WorkloadApiClient

Parameters:

watcher - an instance that implements a Watcher.

fetchX509Bundles

public X509BundleSet fetchX509Bundles()
                               throws X509BundleException

Fetches the X.509 bundles on a one-shot blocking call.

Specified by:

fetchX509Bundles in interface WorkloadApiClient

Returns:

an instance of a X509BundleSet containing the X.509 bundles keyed by TrustDomain

Throws:

X509BundleException - if there is an error fetching or processing the X.509 bundles

watchX509Bundles

public void watchX509Bundles(@NonNull
 @NonNull Watcher<X509BundleSet> watcher)

Watches for X.509 bundles updates.

A new Stream to the Workload API is opened for each call to this method, so that the client starts getting updates immediately after the Stream is ready and doesn't have to wait until the Workload API dispatches the next update.

Specified by:

watchX509Bundles in interface WorkloadApiClient

Parameters:

watcher - an instance that implements a Watcher for X509BundleSet.

fetchJwtSvid

public JwtSvid fetchJwtSvid(@NonNull
 @NonNull String audience,
 String... extraAudience)
                     throws JwtSvidException

Fetches a SPIFFE JWT-SVID on one-shot blocking call.

Specified by:

fetchJwtSvid in interface WorkloadApiClient

Parameters:

audience - the audience of the JWT-SVID

extraAudience - the extra audience for the JWT_SVID

Returns:

an instance of a JwtSvid

Throws:

JwtSvidException - if there is an error fetching or processing the JWT from the Workload API

fetchJwtSvid

public JwtSvid fetchJwtSvid(@NonNull
 @NonNull SpiffeId subject,
 @NonNull
 @NonNull String audience,
 String... extraAudience)
                     throws JwtSvidException

Fetches a SPIFFE JWT-SVID on one-shot blocking call.

Specified by:

fetchJwtSvid in interface WorkloadApiClient

Parameters:

subject - a SPIFFE ID

audience - the audience of the JWT-SVID

extraAudience - the extra audience for the JWT_SVID

Returns:

an instance of a JwtSvid

Throws:

JwtSvidException - if there is an error fetching or processing the JWT from the Workload API

fetchJwtSvids

public List<JwtSvid> fetchJwtSvids(@NonNull
 @NonNull String audience,
 String... extraAudience)
                            throws JwtSvidException

Fetches all SPIFFE JWT-SVIDs on one-shot blocking call.

Specified by:

fetchJwtSvids in interface WorkloadApiClient

Parameters:

audience - the audience of the JWT-SVID

extraAudience - the extra audience for the JWT_SVID

Returns:

all of JwtSvid object

Throws:

JwtSvidException - if there is an error fetching or processing the JWT from the Workload API

fetchJwtSvids

public List<JwtSvid> fetchJwtSvids(@NonNull
 @NonNull SpiffeId subject,
 @NonNull
 @NonNull String audience,
 String... extraAudience)
                            throws JwtSvidException

Fetches a SPIFFE JWT-SVID on one-shot blocking call.

Specified by:

fetchJwtSvids in interface WorkloadApiClient

Parameters:

subject - a SPIFFE ID

audience - the audience of the JWT-SVID

extraAudience - the extra audience for the JWT_SVID

Returns:

Throws:

JwtSvidException - if there is an error fetching or processing the JWT from the Workload API

fetchJwtBundles

public JwtBundleSet fetchJwtBundles()
                             throws JwtBundleException

Fetches the JWT bundles for JWT-SVID validation, keyed by trust domain.

Specified by:

fetchJwtBundles in interface WorkloadApiClient

Returns:

an instance of a JwtBundleSet

Throws:

JwtBundleException - when there is an error getting or processing the response from the Workload API

validateJwtSvid

public JwtSvid validateJwtSvid(@NonNull
 @NonNull String token,
 @NonNull
 @NonNull String audience)
                        throws JwtSvidException

Validates the JWT-SVID token. The parsed and validated JWT-SVID is returned.

Specified by:

validateJwtSvid in interface WorkloadApiClient

Parameters:

token - JWT token

audience - audience of the JWT

Returns:

a JwtSvid if the token and audience could be validated.

Throws:

JwtSvidException - when the token cannot be validated with the audience

watchJwtBundles

public void watchJwtBundles(@NonNull
 @NonNull Watcher<JwtBundleSet> watcher)

Watches for JWT bundles updates.

A new Stream to the Workload API is opened for each call to this method, so that the client starts getting updates immediately after the Stream is ready and doesn't have to wait until the Workload API dispatches the next update based on the SVIDs TTL.

Specified by:

watchJwtBundles in interface WorkloadApiClient

Parameters:

watcher - receives the update for JwtBundles.

close

public void close()

Closes this Workload API closing the underlying channel, cancelling the contexts and shutdown the executor service.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable