Repository navigation
docs(core): fix the JWT source examples and document CachedJwtSource - #522
Open
NopeCharon wants to merge 1 commit into
Open
NopeCharon wants to merge 1 commit into
NopeCharon wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Fixes the core README examples that don't compile against the current API, and documents two features that the README didn't cover:
JwtSource.newSource()becomesDefaultJwtSource.newSource().JwtSourceis an interface with no static methods, and the factories areDefaultJwtSource.newSourceandCachedJwtSource.newSource.JwtSource.JwtSourceOptionsbecomes the top-levelJwtSourceOptions.TrustDomain.of(...)becomesTrustDomain.parse(...)in the X.509 and JWT examples.TrustDomain.ofdoesn't exist.newSource(Duration timeout)method, which doesn't exist. They now show theinitTimeoutoption ofX509SourceOptions/JwtSourceOptions. They also explain:spiffe.newX509Source.timeout/spiffe.newJwtSource.timeoutSystem properties are only used when the options don't setinitTimeoutnewSourcethrowsX509SourceException/JwtSourceExceptionwhen the timeout expiresCachedJwtSource, which wasn't mentioned anywhere. It caches JWT-SVIDs per subject and audiences and fetches new ones after half their lifetime.DefaultJwtSourcefetches a new JWT-SVID on every call.JwtSvid.parseAndValidateand aJwtSource, which exceptions it throws, and howparseInsecurediffers.Why
Someone who copies the JWT Source examples gets code that doesn't compile. The timeout docs pointed to an API that isn't there, so the supported way to set a timeout from code wasn't documented.
CachedJwtSourceandJwtSvid.parseAndValidateare part of the public API, but the README didn't describe either of them.How tested
java-spiffe-core/src/testand compiled it with./gradlew :java-spiffe-core:compileTestJavaon JDK 17. The class was removed afterwards. The replaced snippets referenceJwtSource.newSource,JwtSource.JwtSourceOptions,TrustDomain.ofandnewSource(Duration), none of which exist.DefaultX509Source,DefaultJwtSource,CachedJwtSource,JwtSourceOptionsandJwtSvid: timeout fallback and class-load-time property reads, the exceptions thrown on timeout, the cache key and half-lifetime refresh, and the audience, expiry and signature checks with their exceptions.