Add OAuth2ClientInterceptor to handle client credentials flow

[christiangoerdes]

Summary by CodeRabbit

• New Features

  • Added OAuth2 client‑credentials support: the proxy can obtain, cache (with refresh buffering), and inject Bearer tokens into outgoing requests. Token requests use client credentials and optional scope. Configuration options added for token endpoint, client ID, client secret, and scope. Token acquisition failures return a gateway-style error response.

• Refactor

  • Improved token-request building with a new utility for creating URL-encoded query strings and cleaner encoding handling.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds OAuth2ClientInterceptor that performs client-credentials token acquisition (optional scope), caches tokens until near expiry, injects Authorization: Bearer into outbound requests, and returns 502 ProblemDetails on token acquisition failure.

Changes

OAuth2 Client Credentials Token Injection

Layer / File(s)	Summary
Class initialization and configuration core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2ClientInterceptor.java	OAuth2ClientInterceptor declares tokenUrl, clientId, clientSecret, scope, token cache state, an ObjectMapper, and an HttpClient. init() wires the HTTP client from the router factory. Public annotated getters/setters expose configuration.
Request handling and injection core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2ClientInterceptor.java	handleRequest() obtains an access token, sets Authorization: Bearer <token> on the outgoing request, and aborts with a 502 ProblemDetails on token acquisition failure (with logging).
Token cache, expiry, and fetch core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2ClientInterceptor.java, core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2TokenBody.java, core/src/main/java/com/predic8/membrane/core/util/URLParamUtil.java	In-memory token caching keyed by expiry with a synchronized refresh path; builds form-urlencoded POST body (grant_type=client_credentials and optional scope) using URLParamUtil.createQueryStringOmitNullValues, sends it with Authorization: Basic <base64(urlEncoded(clientId):urlEncoded(clientSecret))>, requires HTTP 200, parses JSON for access_token and expires_in, and updates or disables cache based on expires_in.

Sequence Diagram

sequenceDiagram
  participant Client
  participant OAuth2ClientInterceptor
  participant RouterHttpClient
  participant AuthorizationServer
  Client->>OAuth2ClientInterceptor: Incoming request
  OAuth2ClientInterceptor->>OAuth2ClientInterceptor: getAccessToken() (check cache)
  alt token missing/expired
    OAuth2ClientInterceptor->>RouterHttpClient: POST tokenUrl (form body, Basic auth)
    RouterHttpClient->>AuthorizationServer: POST /token
    AuthorizationServer->>RouterHttpClient: 200 { access_token, expires_in }
    RouterHttpClient->>OAuth2ClientInterceptor: token response
    OAuth2ClientInterceptor->>OAuth2ClientInterceptor: parse JSON, update cache
  end
  OAuth2ClientInterceptor->>Client: Forward request with Authorization: Bearer <token>

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• membrane/api-gateway#2091: Related changes around OAuth2 token-body construction and client-auth parameter handling.

Suggested labels

Prio-1

Suggested reviewers

• predic8

Poem

🐇 In tunnels of HTTP I quietly creep,
I fetch client tokens while others sleep.
I cache them safe until expiry peeps,
Then inject a Bearer and send your heaps.
Hop—your request is ready, swift and neat.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding OAuth2ClientInterceptor to handle OAuth2 client credentials flow, which is the primary addition in this changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch oAuth2Client-interceptor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[christiangoerdes]

/ok-to-test

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2ClientInterceptor.java`:
- Around line 61-66: The current Bad Gateway ProblemDetails built in
OAuth2ClientInterceptor (the gateway(...).title("Bad Gateway").status(502)...
.detail("Could not obtain an OAuth2 access token from
%s.".formatted(tokenUrl)).buildAndSetResponse(exc)) leaks backend topology by
including tokenUrl in the client-visible detail; replace that formatted detail
with a generic message (e.g. "Could not obtain an OAuth2 access token.") so the
call to .detail(...) does not contain tokenUrl or any internal hostnames/URLs,
and keep the original exception logged server-side (exc) for diagnostics without
returning internal addresses to the client.
- Around line 112-114: The buildBasicAuthorization() method currently joins raw
clientId and clientSecret with ":" before Base64, which fails for credentials
requiring form-encoding; update it to call the existing
encodeClientCredential(...) (or implement it if missing) to percent-encode each
component using application/x-www-form-urlencoded (e.g. URLEncoder.encode(value,
UTF_8.name())), then join encodedClientId + ":" + encodedClientSecret and pass
that to getEncoder().encodeToString(...), preserving the "Basic " prefix and
UTF_8 usage.
- Around line 53-56: handleRequest currently calls fetchAccessToken() on every
request; change OAuth2ClientInterceptor to cache the access token and its expiry
(use fields like cachedToken and tokenExpiryEpochMillis) and only call
fetchAccessToken() when the cached token is missing or about to expire (e.g.
within a small refresh window of now >= tokenExpiryEpochMillis -
refreshMarginMillis). Protect token reads/writes with synchronization (or a
ReentrantLock) so only one thread performs fetchAccessToken() and updates
cachedToken/tokenExpiryEpochMillis while others wait or use the previous token
if still valid; ensure fetchAccessToken() returns both token and expires_in so
you compute tokenExpiryEpochMillis from current time + expires_in*1000.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0e35c861-8fe8-49ae-9460-e12d17aa5509

📥 Commits

Reviewing files that changed from the base of the PR and between ccef747 and 47f8226.

📒 Files selected for processing (1)

• core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/OAuth2ClientInterceptor.java

[membrane-ci-server]

This pull request needs "/ok-to-test" from an authorized committer.