Skip to content

feat(provider): add SpiffeIdVerifier factory methods - #524

Merged
maxlambrecht merged 1 commit into
spiffe:mainfrom
NopeCharon:feat/spiffe-id-verifier-factories
Nov 20, 2026
Merged

maxlambrecht merged 1 commit into
spiffe:mainfrom
NopeCharon:feat/spiffe-id-verifier-factories

Conversation

@NopeCharon

Copy link
Copy Markdown
Contributor

What

Adds static factory methods to SpiffeIdVerifier for the common peer authorization rules:

  • SpiffeIdVerifier.acceptAny() accepts any SPIFFE ID.
  • SpiffeIdVerifier.acceptId(SpiffeId) accepts only the given SPIFFE ID.
  • SpiffeIdVerifier.acceptOneOf(SpiffeId...) and acceptOneOf(Collection<SpiffeId>) accept any of the given SPIFFE IDs.
  • SpiffeIdVerifier.acceptMemberOf(TrustDomain) accepts any SPIFFE ID in the trust domain.
SslContextOptions options = SslContextOptions
        .builder()
        .x509Source(x509Source)
        .spiffeIdVerifier(SpiffeIdVerifier.acceptMemberOf(TrustDomain.parse("example.org")))
        .build();
SSLContext sslContext = SpiffeSslContextFactory.getSslContext(options);

Details:

  • A null argument, or a null element in acceptOneOf, throws NullPointerException when the verifier is created, not during a handshake.
  • acceptOneOf copies the SPIFFE IDs, so later changes to the array or collection don't affect the verifier. The Javadoc and README point to acceptedSpiffeIdsSupplier for a set that changes over time. With no SPIFFE IDs, the verifier rejects every peer.
  • Rejections throw SpiffeVerificationException. acceptId and acceptOneOf use the message of the existing Supplier-based verifier (SPIFFE ID ... in X.509 certificate is not accepted), and acceptMemberOf says which trust domain was expected.
  • SpiffeTrustManager(BundleSource) now uses acceptAny() instead of its private accept-any constant. Behavior is unchanged.
  • SpiffeIdVerifier gets a class-level Javadoc.
  • The provider README lists the factory methods in the "Verify peer SPIFFE IDs with a custom verifier" section, uses acceptMemberOf in the example, and keeps an example of a hand-written verifier for other rules (a path prefix). The changelog lists the methods under Unreleased.

Why

#521 made SpiffeIdVerifier usable from SslContextOptions, but callers still had to write the verifier themselves even for the usual rules, such as "any workload in my trust domain" (the README example was exactly that lambda). go-spiffe provides these rules as tlsconfig.AuthorizeAny, AuthorizeID, AuthorizeOneOf and AuthorizeMemberOf. Ready-made verifiers also avoid small mistakes in hand-written ones, such as comparing SPIFFE ID strings or trust domain names instead of using SpiffeId.equals and memberOf.

Compatibility: this only adds static methods to the SpiffeIdVerifier interface, which is binary and source compatible for existing implementations and lambdas. :java-spiffe-provider:japicmp passes.

How tested

  • New SpiffeIdVerifierTest:
    • acceptAny accepts IDs from any trust domain, including a root ID
    • acceptId accepts an equal SPIFFE ID and rejects other paths, a child path and another trust domain, with the expected message
    • acceptOneOf (array and collection) accepts the given IDs and rejects others; changes to the array or collection after creation don't affect the verifier; an empty set rejects everything
    • acceptMemberOf accepts IDs in the trust domain (including one parsed from an upper-case trust domain) and rejects other trust domains, including example.org.other, with the expected message
    • null arguments and null elements throw NullPointerException with the expected messages; a null SPIFFE ID is rejected by every verifier
  • SpiffeSslContextFactoryTest: mutual TLS handshake between two in-memory SSLEngines, with the client using acceptId(server) and the server using acceptMemberOf(example.org). The handshake succeeds, and with acceptOneOf of a different ID it fails with an SSLHandshakeException caused by the verifier's SpiffeVerificationException.
  • Commands, on JDK 17: ./gradlew :java-spiffe-provider:test :java-spiffe-provider:javadoc :java-spiffe-provider:japicmp (108 provider tests pass).

@maxlambrecht maxlambrecht left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! These factories are great additions!

SslContextOptions and SpiffeTrustManager accept a SpiffeIdVerifier, but
every caller has to write the verifier by hand, even for the common
authorization rules. go-spiffe ships these rules as tlsconfig.AuthorizeAny,
AuthorizeID, AuthorizeOneOf and AuthorizeMemberOf.

Add static factory methods to the SpiffeIdVerifier interface:

- acceptAny() accepts any SPIFFE ID
- acceptId(SpiffeId) accepts only the given SPIFFE ID
- acceptOneOf(SpiffeId...) and acceptOneOf(Collection<SpiffeId>) accept
  any of the given SPIFFE IDs, copied when the verifier is created
- acceptMemberOf(TrustDomain) accepts any SPIFFE ID in the trust domain

Null arguments and null elements are rejected with a
NullPointerException when the verifier is created. A verifier created
with no SPIFFE IDs rejects every peer. Rejections throw
SpiffeVerificationException with the same message format as the
existing Supplier-based verifier.

SpiffeTrustManager now uses acceptAny() instead of its private
accept-any constant. Adding static methods to an interface is binary
compatible, and japicmp passes.

Document the factory methods in the provider README, keep an example of
a custom verifier for other rules, and add a changelog entry.

Signed-off-by: NopeCharon <115794254+NopeCharon@users.noreply.github.com>
@maxlambrecht
maxlambrecht force-pushed the feat/spiffe-id-verifier-factories branch from 709e3b4 to c659925 Compare November 20, 2026 02:42
@maxlambrecht
maxlambrecht merged commit b4841f5 into spiffe:main Nov 20, 2026
8 checks passed
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.

2 participants