KeyVault JCA: lazy-load certificate material and add alias regex filtering - #49774
Open
Rujun Chen (rujche) wants to merge 39 commits into
Open
Conversation
Rujun Chen (rujche)
added
azure-spring
Contributor
There was a problem hiding this comment.
Pull request overview
This PR enhances azure-security-keyvault-jca to reduce unnecessary Key Vault reads by (1) allowing users to configure a subset of certificate aliases to consider and (2) lazily loading certificate details only when a specific alias is requested—addressing the scenario described in #39487 (iterating/fetching all aliases when only one is configured).
Changes:
- Added
azure.keyvault.jca.certificatessystem property support to filter Key Vault certificate aliases to a configured subset. - Implemented lazy loading of Key Vault certificate key/certificate/chain data per alias (instead of eagerly loading all details on refresh).
- Updated tests and documentation (README + CHANGELOG) to cover and describe the new behavior.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/keyvault/azure-security-keyvault-jca/src/main/java/com/azure/security/keyvault/jca/KeyVaultKeyStore.java | Wires configured alias filtering into keystore initialization and routes Key Vault lookups through lazy-loading accessors. |
| sdk/keyvault/azure-security-keyvault-jca/src/main/java/com/azure/security/keyvault/jca/implementation/certificates/KeyVaultCertificates.java | Implements configured-alias filtering and lazy loading of certificate details per alias. |
| sdk/keyvault/azure-security-keyvault-jca/src/test/java/com/azure/security/keyvault/jca/KeyVaultKeyStoreUnitTest.java | Adds unit coverage for parsing configured aliases and verifying they are passed into KeyVaultCertificates. |
| sdk/keyvault/azure-security-keyvault-jca/src/test/java/com/azure/security/keyvault/jca/implementation/certificates/KeyVaultCertificatesTest.java | Adds unit coverage ensuring alias listing is not eager and that only requested/configured aliases trigger Key Vault reads. |
| sdk/keyvault/azure-security-keyvault-jca/README.md | Documents the new azure.keyvault.jca.certificates configuration option. |
| sdk/keyvault/azure-security-keyvault-jca/CHANGELOG.md | Records the new filtering + lazy-loading features for the upcoming release. |
Listing aliases ran outside the instance lock, so two concurrent refreshes could apply their results in completion order rather than start order. A slow refresh could overwrite a newer alias list and still stamp lastRefreshTime, pinning the stale list for the whole refresh interval. Every caller also issued its own list request while only one result was kept. Move the listing into the existing synchronized block and hoist the double check ahead of it. The stale-client identity guard is no longer reachable there because updateKeyVaultClient holds the same lock, so it is removed. The per-alias lazy loaders keep their guards and still run their remote calls outside the lock.
The comma separated azure.keyvault.jca.certificate-alias-filter-patterns
property could not carry arbitrary regexes: a comma is valid regex
syntax, so a bounded quantifier such as \d{1,5} was split into \d{1 and
5} and failed to compile. No delimiter is safe here, because a regex can
contain any printable character.
Replace it with azure.keyvault.jca.certificate-alias-filter-pattern,
optionally suffixed to configure more than one filter. The suffix only
keeps property names unique and does not affect evaluation, since
include patterns are matched with anyMatch and exclude patterns with
noneMatch. The ! prefix for exclude patterns is unchanged.
The replaced property was introduced in this unreleased version, so it
is removed rather than deprecated.
6 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
Suppressed comments (1)
sdk/keyvault/azure-security-keyvault-jca/src/main/java/com/azure/security/keyvault/jca/KeyVaultKeyStore.java:64
- The configured system property name for alias filtering is hard-coded here as
azure.keyvault.jca.certificate-alias-filter-pattern, but the PR description/notes indicate the property was renamed toazure.keyvault.jca.certificate-alias-filter-patterns(plural). This inconsistency will confuse users and makes it unclear which property is actually supported. Please align the property name across code, README, CHANGELOG, and tests (or explicitly support both names for backward/forward compatibility).
static final String CERTIFICATE_ALIAS_FILTER_PATTERN_PROPERTY
= "azure.keyvault.jca.certificate-alias-filter-pattern";
vcolin7
reviewed
Aug 6, 2026
vcolin7
left a comment
vcolin7
left a comment
Member
There was a problem hiding this comment.
Suggesting some wording changes for clarity.
Comment on lines
+161
to
+163
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.1='^prod-.*' | ||
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.2='^cert-\d{1,5}$' | ||
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.exclude-old='!.*-old$' |
Member
There was a problem hiding this comment.
Small suggestion to make the following points that talk about case sensitivity easier to read:
Suggested change
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.1='^prod-.*' | |
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.2='^cert-\d{1,5}$' | |
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.exclude-old='!.*-old$' | |
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.1='^cert-.*' | |
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.prod='^prod-\d{1,5}$' | |
| -Dazure.keyvault.jca.certificate-alias-filter-pattern.exclude-old='!.*-old$' |
Comment on lines
+166
to
+170
| * Use an include pattern directly and an exclude pattern with a `!` prefix. | ||
| * A suffix can be a number or a string. It only keeps the property names unique and does not affect evaluation, so the filters are unordered. Property names are case-sensitive, which means `.prod` and `.PROD` are two different filters. | ||
| * Patterns use full-alias matching (`Pattern.matcher(alias).matches()`). | ||
| * An alias is loaded only if it matches at least one include pattern, or if no include pattern is configured, and matches no exclude pattern. | ||
| * An invalid pattern fails fast with an `IllegalArgumentException` that names the offending pattern. |
Member
There was a problem hiding this comment.
Suggested change
| * Use an include pattern directly and an exclude pattern with a `!` prefix. | |
| * A suffix can be a number or a string. It only keeps the property names unique and does not affect evaluation, so the filters are unordered. Property names are case-sensitive, which means `.prod` and `.PROD` are two different filters. | |
| * Patterns use full-alias matching (`Pattern.matcher(alias).matches()`). | |
| * An alias is loaded only if it matches at least one include pattern, or if no include pattern is configured, and matches no exclude pattern. | |
| * An invalid pattern fails fast with an `IllegalArgumentException` that names the offending pattern. | |
| * Inclusion patterns are used directly and exclusion patterns start with a `!` prefix. | |
| * A suffix for the property name can be a number or a string; it is used to keep the property names unique and does not affect evaluation. The filters are unordered. Property names are case-sensitive, which means `.prod` and `.PROD` are two different filters. | |
| * Patterns use full-alias matching (`Pattern.matcher(alias).matches()`). | |
| * An alias is loaded only if it matches at least one inclusion pattern, or if no inclusion pattern is configured, and matches no exclusion pattern. | |
| * An invalid pattern fails fast with an `IllegalArgumentException` that names the offending pattern. |
| * An alias is loaded only if it matches at least one include pattern, or if no include pattern is configured, and matches no exclude pattern. | ||
| * An invalid pattern fails fast with an `IllegalArgumentException` that names the offending pattern. | ||
|
|
||
| Quote the value as required by your shell, otherwise characters such as `^` and `\` can be altered before the JVM receives them: |
Member
There was a problem hiding this comment.
Suggested change
| Quote the value as required by your shell, otherwise characters such as `^` and `\` can be altered before the JVM receives them: | |
| Quote the filter value as required by your shell, otherwise characters such as `^` and `\` can be altered before the JVM receives them: |
|
|
||
| #### Filtering Key Vault certificate aliases | ||
|
|
||
| Each filter is configured as its own property, so no delimiter is required and a pattern may contain any character: |
Member
There was a problem hiding this comment.
Suggested change
| Each filter is configured as its own property, so no delimiter is required and a pattern may contain any character: | |
| Each filter is configured as its own property, so no delimiter is required and a pattern may contain any character. Filters use Java-based regex: |
|
|
||
| ### Features Added | ||
| - Added lazy loading for Key Vault certificate details in the JCA keystore. Certificate details are now loaded by alias when requested, avoiding unnecessary reads for unconfigured certificates. ([#49774](https://github.com/Azure/azure-sdk-for-java/pull/49774)) | ||
| - Added support for `azure.keyvault.jca.certificate-alias-filter-pattern` to filter Key Vault certificate aliases with include/exclude regex patterns. Include patterns are configured directly and exclude patterns are prefixed with `!`. Configure more than one filter by appending a suffix to the property name, such as `azure.keyvault.jca.certificate-alias-filter-pattern.1`, so that a pattern can contain any character. If no such property is configured, alias filtering is disabled and all discovered Key Vault aliases remain eligible for lazy loading. ([#39487](https://github.com/Azure/azure-sdk-for-java/issues/39487)) |
Member
There was a problem hiding this comment.
Suggested change
| - Added support for `azure.keyvault.jca.certificate-alias-filter-pattern` to filter Key Vault certificate aliases with include/exclude regex patterns. Include patterns are configured directly and exclude patterns are prefixed with `!`. Configure more than one filter by appending a suffix to the property name, such as `azure.keyvault.jca.certificate-alias-filter-pattern.1`, so that a pattern can contain any character. If no such property is configured, alias filtering is disabled and all discovered Key Vault aliases remain eligible for lazy loading. ([#39487](https://github.com/Azure/azure-sdk-for-java/issues/39487)) | |
| - Added support for `azure.keyvault.jca.certificate-alias-filter-pattern` to filter Key Vault certificate aliases with inclusion/exclusion regex patterns. Inclusion patterns are configured directly and exclusion patterns are prefixed with `!`. Configure more than one filter by appending a suffix to the property name, such as `azure.keyvault.jca.certificate-alias-filter-pattern.1`. A pattern can contain any character as long as the regex is correct. If no filter property is configured, alias filtering is disabled and all discovered Key Vault aliases remain eligible for lazy loading. ([#39487](https://github.com/Azure/azure-sdk-for-java/issues/39487)) |
vcolin7
reviewed
Aug 6, 2026
vcolin7
left a comment
vcolin7
left a comment
Member
There was a problem hiding this comment.
Some more functional comments
| if (!Objects.isNull(key)) { | ||
| certificateKeys.put(alias, key); | ||
| synchronized (this) { | ||
| if (loadedCertificateChainAliases.contains(alias) || !aliases.contains(alias)) { |
Member
There was a problem hiding this comment.
Multiple callers can pass this check before the alias is marked as loaded, so concurrent TLS handshakes can issue duplicate Key Vault requests; the loaded set only deduplicates publication. We should consider adding per-alias/per-material single-flight state, like an in-flight future, so callers share one fetch and avoid startup latency and throttling.
| } | ||
|
|
||
| try { | ||
| Certificate[] loadedCertificateChain = currentKeyVaultClient.getCertificateChain(alias); |
Member
There was a problem hiding this comment.
The chain and key are fetched independently through versionless aliases, so a rotation between their first accesses can cache a v1 chain with a v2 private key and break TLS indefinitely when refresh is disabled. We should resolve and pin one certificate version per alias, ideally caching its material as a single immutable bundle.
| try { | ||
| Certificate[] loadedCertificateChain = currentKeyVaultClient.getCertificateChain(alias); | ||
| synchronized (this) { | ||
| if (currentKeyVaultClient != keyVaultClient |
Member
There was a problem hiding this comment.
This guard handles client replacement but not a refresh on the same client, so a load started before refreshCertificates() can repopulate the cleared cache with stale material. We could track a cache generation, capture it before the remote call, and discard the result if a refresh or invalidation advanced that generation.
| Certificate[] certificateChain = keyVaultClient.getCertificateChain(alias); | ||
| if (!Objects.isNull(certificateChain)) { | ||
| certificateChains.put(alias, certificateChain); | ||
| } catch (RuntimeException exception) { |
Member
There was a problem hiding this comment.
This converts every non-2xx failure, including 403 and 429, into a null chain, conflating a failed load with an absent entry and potentially causing lower-priority fallback or an unrelated NPE in KeyVaultKeyManager. I'd keep the entry retryable but propagate or wrap service failures, reserving an empty chain for a genuine no-chain result.
This was referenced Aug 6, 2026
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.
Description
This PR completes #39487 in
azure-security-keyvault-jcaand also finalizes the follow-up lazy-loading/thread-safety refinements requested during review.What changed
sdk/keyvault/azure-security-keyvault-jca/checkstyle-suppressions.xmlupdates are script-generated viaeng/scripts/linting_suppression_generator.py(not manually edited).KeyVaultCertificatesfor certificate, key, and certificate chain by alias.azure.keyvault.jca.certificate-alias-filter-patternconfigures a single filter.azure.keyvault.jca.certificate-alias-filter-pattern.1orazure.keyvault.jca.certificate-alias-filter-pattern.prod.!.Pattern.matcher(alias).matches()).KeyVaultCertificates:KeyVaultKeyStorelookup pathing and filter-pattern collection.README.md,CHANGELOG.md).KeyVaultKeyStoreUnitTestKeyVaultCertificatesTestWhy one property per filter
Each property value is a regex, so no delimiter is safe: a comma is valid regex syntax, and a bounded quantifier such as
\d{1,5}would be split into\d{1and5}and fail to compile. Escaping does not help either, because\is already the regex escape character, so\,cannot be distinguished from a legitimate regex escape. Giving each filter its own property removes the delimiter entirely, so a pattern may contain any character.A suffix only keeps property names unique and does not affect evaluation, because include patterns are matched with
anyMatchand exclude patterns withnoneMatch. Property names are case-sensitive, so.prodand.PRODare two distinct filters.Quote the value as required by your shell. On
cmd.exein particular,-D...='^prod-.*'arrives as'prod-.*', because single quotes are not stripped and^is the escape character; the result still compiles as a regex but matches nothing. The README documents the correct quoting per shell.Validation
mvn -f sdk/keyvault/azure-security-keyvault-jca/pom.xml clean test: 115 tests pass.mvn -f sdk/keyvault/azure-security-keyvault-jca/pom.xml checkstyle:check spotbugs:check: 0 Checkstyle violations, 0 SpotBugs findings.Notes
azure.keyvault.jca.certificate-alias-filter-patternstoazure.keyvault.jca.certificate-alias-filter-patternis not a breaking change, and the old name is removed rather than deprecated.mainhas been merged in after the 2.12.0 release, so the release notes now target2.13.0-beta.1.All SDK Contribution checklist:
General Guidelines and Best Practices
Testing Guidelines