Skip to content

docs(core): fix the JWT source examples and document CachedJwtSource - #522

Open
NopeCharon wants to merge 1 commit into
spiffe:mainfrom
NopeCharon:docs/core-readme-jwt-source
Open

NopeCharon wants to merge 1 commit into
spiffe:mainfrom
NopeCharon:docs/core-readme-jwt-source

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

What

Fixes the core README examples that don't compile against the current API, and documents two features that the README didn't cover:

  • JWT Source: JwtSource.newSource() becomes DefaultJwtSource.newSource(). JwtSource is an interface with no static methods, and the factories are DefaultJwtSource.newSource and CachedJwtSource.newSource. JwtSource.JwtSourceOptions becomes the top-level JwtSourceOptions.
  • TrustDomain.of(...) becomes TrustDomain.parse(...) in the X.509 and JWT examples. TrustDomain.of doesn't exist.
  • Both timeout sections said to pass the timeout to a newSource(Duration timeout) method, which doesn't exist. They now show the initTimeout option of X509SourceOptions / JwtSourceOptions. They also explain:
    • the spiffe.newX509Source.timeout / spiffe.newJwtSource.timeout System properties are only used when the options don't set initTimeout
    • the properties are read when the source class is loaded
    • newSource throws X509SourceException / JwtSourceException when the timeout expires
  • New "Cache JWT-SVIDs" subsection about CachedJwtSource, which wasn't mentioned anywhere. It caches JWT-SVIDs per subject and audiences and fetches new ones after half their lifetime. DefaultJwtSource fetches a new JWT-SVID on every call.
  • New "Validate JWT-SVIDs" section: validating a token received from another workload with JwtSvid.parseAndValidate and a JwtSource, which exceptions it throws, and how parseInsecure differs.
  • Changelog entry under Documentation.

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. CachedJwtSource and JwtSvid.parseAndValidate are part of the public API, but the README didn't describe either of them.

How tested

  • Put every new and changed snippet into a temporary class under java-spiffe-core/src/test and compiled it with ./gradlew :java-spiffe-core:compileTestJava on JDK 17. The class was removed afterwards. The replaced snippets reference JwtSource.newSource, JwtSource.JwtSourceOptions, TrustDomain.of and newSource(Duration), none of which exist.
  • Checked the described behavior against DefaultX509Source, DefaultJwtSource, CachedJwtSource, JwtSourceOptions and JwtSvid: 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.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant