Support automatic OAuth client-credentials token refresh - #838

Merged

PierreBtz merged 7 commits into

cloudbees-oss:masterfrom

chrisrentsman:cr/tokens

Aug 27, 2026

chrisrentsman commented Aug 24, 2026

Contributor

Summary

Adds support for Zendesk's OAuth client_credentials grant so a Zendesk client can mint and refresh short-lived access tokens instead of requiring a pre-minted OAuth token.

Addresses #829.

Changes

Commit 1: Base implementation
- Add HttpTokenMinter class for minting OAuth tokens, taking care to prevent credential leaks.
- Add SharedFutureTokenProvider class for handling thread-safe token caching and refresh.
  - Refresh begins when the current token's remaining lifetime reaches a configurable threshold (50% by default).
  - One elected leader thread synchronously performs and publishes the refresh result.
  - While the cached token remains unexpired/usable, concurrent callers continue to use it rather than block.
  - If no usable cached token exists, concurrent callers await the result of the leader's in-flight mint attempt.
  - A failed proactive refresh is non-fatal so long as a usable cached token exists.
- Inject the current bearer token when building requests.
- Add Zendesk.Builder configuration.
- Add Zendesk#warmUp() for clients who would like to mint the OAuth token ahead of the first request.
- Surface token-minting failures through ZendeskOAuthException when no usable token remains.
Commit 2: Add backoff on refresh failures
- Add backoff logic in SharedFutureTokenProvider to suppress proactive mint attempts for 10 seconds after a failed mint attempt while a usable cached token remains.

Validation

mvn verify using JDK 11.
Stress-tested thread safety using a local custom harness with soak/herd tests and jcstress (not included in the PR).

References:

Chris Rentsman added 2 commits

August 24, 2026 09:26


          Support automated oauth token refresh for client_credentials auth

7d5ff7d


          Backoff on failed oauth mint attempts so long as there is still a ser…

f73a0df

…vable token

chrisrentsman requested review from PierreBtz and duemir as code owners

August 24, 2026 15:03

Helmsdown commented Aug 24, 2026 •

edited

Loading

Contributor

@PierreBtz this is in reference to #829. (heh, Captain obvious here. I missed the reference that is clearly at the top of the PR description :-D )

PierreBtz reviewed

View reviewed changes

PierreBtz left a comment

Collaborator

Thanks for the contribution! I still have to run some tests on this PR but this looks very promising.

src/main/java/org/zendesk/client/v2/HttpTokenMinter.java Outdated

+               *
+               * @see <a href="https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/">
+               *     OAuth grant type tokens</a>
+               * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
             * @since FIXME
          
             * @since 1.6.0

chrisrentsman Aug 26, 2026

Contributor Author

Updated all of these in 5ebbaaa. Thanks!

src/main/java/org/zendesk/client/v2/Zendesk.java Outdated

+                 * does nothing when there is nothing to prepare.
+                 *
+                 * @throws ZendeskOAuthException if minting fails
+                 * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
               * @since FIXME
          
               * @since 1.6.0

src/main/java/org/zendesk/client/v2/Zendesk.java Outdated

+                   * Default requested token lifetime. 30 minutes: short enough to limit the exposure of a leaked
+                   * token, long enough to keep minting infrequent.
+                   *
+                   * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
                 * @since FIXME
          
                 * @since 1.6.0

src/main/java/org/zendesk/client/v2/Zendesk.java Outdated

+                  /**
+                   * Default refresh threshold. Refreshes when the current token has half its lifetime left.
+                   *
+                   * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
                 * @since FIXME
          
                 * @since 1.6.0

src/main/java/org/zendesk/client/v2/Zendesk.java Outdated

+                   * @param clientSecret the OAuth client's secret
+                   * @param scope space-separated scopes to request, for example {@code "tickets:read"}
+                   * @return this builder instance
+                   * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
                 * @since FIXME
          
                 * @since 1.6.0

src/main/java/org/zendesk/client/v2/TokenProvider.java Outdated

+               * Supplies a currently-usable bearer token. Called on every request from many threads at once, so
+               * implementations must be thread-safe and may block while a token is minted.
+               *
+               * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
             * @since FIXME
          
             * @since 1.6.0

src/main/java/org/zendesk/client/v2/SharedFutureTokenProvider.java Outdated

+               *       not handed out.
+               * </ol>
+               *
+               * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
             * @since FIXME
          
             * @since 1.6.0

src/main/java/org/zendesk/client/v2/OAuthToken.java Outdated

+              /**
+               * An immutable OAuth access token with the instants it was issued and expires.
+               *
+               * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
             * @since FIXME
          
             * @since 1.6.0

src/main/java/org/zendesk/client/v2/TokenMinter.java Outdated

+              /**
+               * Acquires a brand-new access token. Does no caching, no coordination and no retry.
+               *
+               * @since FIXME

PierreBtz Aug 26, 2026

Collaborator

Suggested change

      
             * @since FIXME
          
             * @since 1.6.0

src/main/java/org/zendesk/client/v2/Zendesk.java Outdated

                   public Zendesk build() {
+                    if (oauthClientCredentialsConfigured) {
+                      Objects.requireNonNull(oauthClientId, "OAuth client id cannot be null");

PierreBtz Aug 26, 2026

Collaborator

Note that a blank ("") oauthClientId would pass this check, yet would not be valid and fail at runtime on the first mint.

chrisrentsman Aug 26, 2026 •

edited

Loading

Contributor Author

Thanks! Added blank checks for all of the new OAuth fields in 2be8014.

PierreBtz added the enhancement label

PierreBtz mentioned this pull request

Reset Awaitility customizations in RealSmokeTest #839

Merged

PierreBtz reviewed

View reviewed changes

src/test/java/org/zendesk/client/v2/SharedFutureTokenProviderTest.java

+                private Future<Result> startMintingLeader(
+                    ExecutorService pool, TokenProvider provider, FakeMinter minter) {
+                  var leader = pool.submit(() -> call(provider));
+                  await().atMost(5, TimeUnit.SECONDS).until(() -> minter.threadsInsideMint.get() == 1);

PierreBtz Aug 26, 2026

Collaborator

There is a problem with this line if you run this test class and RealSmokeTest together:

ERROR] org.zendesk.client.v2.SharedFutureTokenProviderTest.failedMintExpectSameExceptionForAllAwaiters -- Time elapsed: 0.001 s <<< ERROR!
java.lang.IllegalArgumentException: Timeout (5 seconds) must be greater than the poll delay (10 seconds).
	at org.awaitility.core.ConditionFactory.generateConditionSettings(ConditionFactory.java:1141)
	at org.awaitility.core.ConditionFactory.until(ConditionFactory.java:1129)
	at org.zendesk.client.v2.SharedFutureTokenProviderTest.startMintingLeader(SharedFutureTokenProviderTest.java:507)
	at org.zendesk.client.v2.SharedFutureTokenProviderTest.failedMintExpectSameExceptionForAllAwaiters(SharedFutureTokenProviderTest.java:231)

This is because RealSmokeTest globally sets a custom poll value that conflicts with the timeout you chose here:

zendesk-java-client/src/test/java/org/zendesk/client/v2/RealSmokeTest.java

Line 149 in 4c08e5f

Awaitility.setDefaultPollDelay(10, TimeUnit.SECONDS);

. Opened #839 to fix this.

chrisrentsman Aug 26, 2026

Contributor Author

Ah I see, thanks for fixing this up.


          Merge branch 'master' into cr/tokens

5f8e132

PierreBtz previously approved these changes

View reviewed changes

PierreBtz left a comment

Collaborator

I finished preparing the repo to fix the test issue (#839) and to inject the proper credentials in the CI pipeline (#841).

Once the since FIXME and the client-id validation are fixed, we can merge this PR.

Chris Rentsman added 2 commits

August 26, 2026 10:25


          Reject blank OAuth client credentials

2be8014


          Mark OAuth additions as introduced in 1.6.0

5ebbaaa

chrisrentsman dismissed PierreBtz’s stale review via

5ebbaaa

August 26, 2026 15:28


          Merge branch 'master' into cr/tokens

e7ee096

chrisrentsman commented Aug 26, 2026 •

edited

Loading

Contributor Author

I finished preparing the repo to fix the test issue (#839) and to inject the proper credentials in the CI pipeline (#841).

Once the since FIXME and the client-id validation are fixed, we can merge this PR.

Thanks @PierreBtz for the feedback and the prep. I've addressed your feedback and re-ran mvn verify too.


          Merge branch 'master' into cr/tokens

a28f557

PierreBtz approved these changes

View reviewed changes

PierreBtz left a comment

Collaborator

lgtm, thanks!

PierreBtz merged commit f6616c6 into cloudbees-oss:master

3 checks passed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels