Skip to content

feat(client): send a bearer token in the Authorization header - #785

Merged
edeandrea merged 1 commit into
docling-project:mainfrom
WMK666666:bearer-token-auth
Nov 13, 2026
Merged

edeandrea merged 1 commit into
docling-project:mainfrom
WMK666666:bearer-token-auth

Conversation

@WMK666666

@WMK666666 WMK666666 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

docling-serve can require an API key of its own: with DOCLING_SERVE_API_KEY set, every request must
carry it in the X-Api-Key header, which is what the existing apiKey option sends. It can also be put
behind a proxy that authenticates the caller on a bearer token — the oauth-proxy deployment in its docs
is one such setup.

DoclingServeClient only knew the API key, so there was no way to talk to a docling-serve sitting behind
that proxy.

Change

  • DoclingServeApiConfig.BEARER_TOKEN (bearerToken, String), with an accessor on the config and a
    setter on DoclingServeApiBuilder.
  • DoclingServeClient.createRequestBuilder sends it as Authorization: Bearer <token> on every request,
    independently of apiKey. Both may be set at once, for a proxy that asks for one and docling-serve
    itself for the other.
  • The Authorization value is masked by the same code that masks X-Api-Key when request logging is on.
  • The setter is not added to the deprecated DoclingApiBuilder interface, which is documented as not
    gaining new configuration options, so third-party implementations of it keep compiling.
    LegacyProviderAdapter therefore reports bearerToken as Unsupported.FAIL: a caller going through a
    legacy factory gets an error naming the factory, instead of the token being silently dropped.

Tests

  • AbstractDoclingServeClientTests#BearerTokenTests (new @Nested class, WireMock): the header is sent,
    it is not sent when no token is configured, and it is independent of the API key. Being part of the
    shared suite, it runs against both the Jackson 2 and the Jackson 3 clients.
  • To build the client under test from a config, the shared suite declares
    protected abstract DoclingServeApi newClient(DoclingServeApiConfig config), implemented by both
    subclasses. DoclingServeApiConfig.toBuilder() and DoclingServeApi.builder() both go through the
    provider, which always builds the implementation it prefers, so they cannot be used for this.
  • DoclingServeClientProviderTests#bearerTokenIsApplied: the DoclingServeApi.builder() path, which is
    the one the docs show, applies the token.
  • DoclingServeApiConfigTests and AbstractDoclingServeClientConfigTests: the new option is reported by
    the config and appears in explicitlySetOptions(), which keeps the guards that every option has an
    accessor and a setter passing.
  • LegacyProviderAdapterTests: bearerToken is listed as unsupported for legacy factories. The
    assertion uses containsOnly, because the expected map comes from Collectors.toUnmodifiableMap and
    has no iteration order.

:docling-serve-api:test and the non-container docling-serve-client tests pass locally. The two
*ClientTests classes start a docling-serve container and need Docker, which this machine doesn't have.

Docs

  • docs/src/doc/docs/docling-serve/serve-client.md: the Authentication section now says that
    docling-serve can require an API key of its own and can also sit behind a proxy that authenticates on a
    bearer token.
  • docs/src/doc/docs/docling-serve/serve-api-provider-migration.md: the provider example maps
    bearerToken, and bearerToken() joins apiKey() and asyncExecutor() as the accessors that return
    null when not set.
  • docs/src/doc/docs/whats-new.md: an entry under Docling Serve → {{ gradle.project_version }}.

@edeandrea

Copy link
Copy Markdown
Contributor

@all-contributors add @WMK666666 for code, tests

@edeandrea edeandrea left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for this, the feature itself looks good and the masking/legacy-adapter handling is nicely thought through. Details are inline, plus a few things on files the PR doesn't touch:

  • Commit message / PR description: docling-serve does have built-in auth: when DOCLING_SERVE_API_KEY is set, every request must carry it in the X-Api-Key header (see configuration.md and APIKeyAuth in app.py). That's what our existing apiKey option is for. The oauth-proxy deployment part is right, but it's one deployment example, not the "normal" deployment. Please reword the commit message accordingly.

  • Provider path: please add a bearer token case to DoclingServeClientProviderTests (alongside baseUrlAndApiKeyAreApplied), so the DoclingServeApi.builder() path, which is the one the docs show, is covered.

  • What's new: please add an entry under Docling Serve → {{ gradle.project_version }} in docs/src/doc/docs/whats-new.md, something like:

    • New bearerToken option — DoclingServeApi.builder().bearerToken(token) sends Authorization: Bearer <token> on every request, for a docling-serve behind a proxy that authenticates on bearer tokens, such as the oauth-proxy deployment. It is independent of apiKey (sent as X-Api-Key), so both can be set. The token is masked when request logging is enabled. Legacy DoclingServeApiBuilderFactory implementations don't support it and fail if it is set.

@allcontributors

Copy link
Copy Markdown
Contributor

@edeandrea

I've put up a pull request to add @WMK666666! 🎉

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

:java_duke: JaCoCo coverage report

Overall Project 52.58% 🟢

There is no coverage information present for the Files changed

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
TestsPassed ✅SkippedFailed
Gradle Test Results (all modules & JDKs)593 ran593 passed0 skipped0 failed
TestResult
No test annotations available

@WMK666666

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review — everything is addressed in 01169cb (rebased onto current main and squashed, so the commit message could be reworded as you asked).

Wording. You're right, I had it backwards. docling-serve does have built-in auth: with DOCLING_SERVE_API_KEY set, every request must carry it in the X-Api-Key header, which is exactly what apiKey sends. The javadoc, the serve-client.md intro and the commit message now say that docling-serve can require an API key of its own and can also sit behind a proxy that authenticates on a bearer token — the oauth-proxy deployment being one such setup, not the normal one — and that bearerToken is independent of apiKey. The paragraph in serve-client.md that contradicted itself two lines later is rewritten.

Provider path. Added bearerTokenIsApplied() to DoclingServeClientProviderTests next to baseUrlAndApiKeyAreApplied(), asserting the header on the DoclingServeApi.builder() path.

Flaky assertion. containsExactly → containsOnly in LegacyProviderAdapterTests. Your diagnosis matches what I see here: UNSUPPORTED comes from Collectors.toUnmodifiableMap, so with two entries the order is whatever the JVM feels like.

Test location. DoclingServeClientBearerTokenTests is deleted; the three tests are now a @Nested class BearerTokenTests in AbstractDoclingServeClientTests, using getWiremockServer() like ClearTests / NonJsonResponseTests. One thing I had to add to make that work: the shared suite has no client-specific builder, and DoclingServeApi.builder() always builds whatever the provider prefers, so a @Nested class using it would still only ever exercise the Jackson 3 client. I added a protected abstract DoclingServeClient.DoclingServeClientBuilder<?, ?> getWiremockClientBuilder() implemented by both DoclingServeJackson2ClientTests and DoclingServeJackson3ClientTests, each pointing at wireMockServer.baseUrl(). The bearerToken(null) test is dropped.

What's new. Added under Docling Serve → {{ gradle.project_version }}, with your wording.

Masking. Understood — leaving that gap alone.

On verification: :docling-serve-api:compileTestJava and :docling-serve-client:compileTestJava build, the non-container test classes (LegacyProviderAdapterTests, DoclingServeApiConfigTests, DoclingServeClientProviderTests, DoclingServeClientBuilderTests) pass, and the new assertions were checked against a WireMock server directly. The two *ClientTests classes that start a docling-serve container need Docker, which this machine doesn't have, so the nested tests are wired into both clients but only CI will execute them.

@edeandrea

Copy link
Copy Markdown
Contributor

Thanks @WMK666666, nice work on the rework, and good catch on the shared suite! You were right: DoclingServeApi.builder() and DoclingServeApiConfig.toBuilder() both go through the provider, which prefers Jackson 3, so a @Nested class built on them only ever exercised the Jackson 3 client.

While verifying that, it turned out the existing suite had the same problem: DoclingServeJackson2ClientTests built its auth and WireMock clients with config().toBuilder()...build(), so ClearTests, NonJsonResponseTests and friends were running against the Jackson 3 client in the Jackson 2 suite too. That's fixed in #796, which is now merged. Could you rebase onto main?

After the rebase, a few things:

  • Replace getWiremockClientBuilder() with a config-based hook. Its implementations call baseUrl(String), which is only a default method on the deprecated DoclingApiBuilder, so it won't survive that interface's removal. test(client): run the shared suite against the client under test #796 adds a private newClient(DoclingServeApiConfig) helper to both subclasses that builds the client under test with DoclingServeJacksonNClient.builder().config(config).build(). Could you turn it into a protected abstract DoclingServeApi newClient(DoclingServeApiConfig config) on AbstractDoclingServeClientTests (implemented by both subclasses) and drop getWiremockClientBuilder()? The tests then become something like:

    var client = newClient(getDoclingClient(false, true).config().toBuilder().bearerToken("my-token").config());

    The subclasses still need a static helper for setUp(), so the override can just delegate to it.

  • Migration guide: docs/src/doc/docs/docling-serve/serve-api-provider-migration.md is now out of date. The "mapping every option" example doesn't pass bearerToken, and it still says "The only exceptions are apiKey() and asyncExecutor(), which return null when not set". bearerToken() belongs in both.

  • Nit: the new tests hard-code "Authorization", while the same test uses HttpOperations.API_KEY_HEADER_NAME. Please use HttpOperations.AUTHORIZATION_HEADER_NAME (in DoclingServeClientProviderTests too).

Everything else from the previous round looks good. Thanks again!

docling-serve can require an API key of its own: with DOCLING_SERVE_API_KEY
set, every request must carry it in the X-Api-Key header, which is what the
existing apiKey option sends. It can also be put behind a proxy that
authenticates the caller on a bearer token, the oauth-proxy deployment in its
docs being one such setup. The client only knew the API key, so there was no
way to talk to a docling-serve sitting behind that proxy.

Add a bearerToken option next to apiKey. It is sent as
"Authorization: Bearer <token>" on every request, independently of the API key,
and it is masked together with the API key when request logging is enabled.

The setter goes on the concrete builders only, not on the deprecated
DoclingApiBuilder interface, which is documented as not gaining new
configuration options and which third-party implementations must keep
compiling. As for every option added since that deprecation,
LegacyProviderAdapter reports it as unsupported, so a caller going through a
legacy factory gets an error naming the factory instead of the token being
silently dropped.

The tests live in a @nested class of AbstractDoclingServeClientTests and build
their client through the newClient(DoclingServeApiConfig) hook the shared suite
declares, so they run against both the Jackson 2 and the Jackson 3 client, and
DoclingServeClientProviderTests covers the DoclingServeApi.builder() path the
docs show. The javadoc, the client docs, whats-new and the provider migration
guide describe both credentials.

Signed-off-by: WMK666666 <[email protected]>
@WMK666666

Copy link
Copy Markdown
Contributor Author

Rebased onto main (f61b80c, so #796 is in) and pushed as one commit, 4965887.

getWiremockClientBuilder() is gone, replaced by newClient(DoclingServeApiConfig). AbstractDoclingServeClientTests now declares

protected abstract DoclingServeApi newClient(DoclingServeApiConfig config);

implemented by both subclasses, and BearerTokenTests builds what it needs the way you sketched:

var client = newClient(getDoclingClient(false, true).config().toBuilder().bearerToken("my-token").config());

One detail worth pointing out: the static helper in each subclass had to be renamed. setUp() is @BeforeAll static, so it still calls a static method, and a class can't carry a static and an instance method with the same signature — so the helper is buildClient(DoclingServeApiConfig) and the override just delegates to it:

@Override
protected DoclingServeApi newClient(DoclingServeApiConfig config) {
  return buildClient(config);
}

Migration guide (serve-api-provider-migration.md): the provider example now maps .bearerToken(config.bearerToken()) next to .apiKey(...), and the sentence reads "The only exceptions are apiKey(), bearerToken() and asyncExecutor(), which return null when not set."

Nit: both BearerTokenTests and DoclingServeClientProviderTests now use HttpOperations.AUTHORIZATION_HEADER_NAME, no string literal.

On the red CI on the previous head: those two initializationError failures are a Testcontainers image pull timing out, not the code —

ContainerFetchException: Can't get Docker image: .../docling-serve:v1.35.0
  Caused by: ConditionTimeoutException: ... RemoteDockerImage was not fulfilled within 2 minutes

All 24 other jobs in that run were green, including docling-serve-client on 17/21/25/27. The rebase also picks up #794, which raises that pull timeout.

Locally on this head: :docling-serve-api:compileTestJava and :docling-serve-client:compileTestJava build, and LegacyProviderAdapterTests, DoclingServeApiConfigTests, DoclingServeClientProviderTests, DoclingServeClientBuilderTests all pass (26 tests). The container-based *ClientTests still can't run here — no Docker on this machine.

@edeandrea edeandrea left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you very much @WMK666666 for this and for working through several rounds of review!

Once CI passes I will merge.

@edeandrea
edeandrea enabled auto-merge (squash) November 13, 2026 13:11
@github-actions

Copy link
Copy Markdown

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

@edeandrea
edeandrea merged commit 4e6b874 into docling-project:main Nov 13, 2026
52 of 53 checks passed
@edeandrea

Copy link
Copy Markdown
Contributor

@all-contributors add @WMK666666 for code, test

@allcontributors

Copy link
Copy Markdown
Contributor

@edeandrea

This project's configuration file has malformed JSON: .all-contributorsrc. Error:: Expected ',' or ']' after array element in JSON at position 7198 (line 277 column 7)

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