[OPIK-6666] [BE] feat: MCP OAuth 2.1 foundations (PR 1/7) — schema, config, domain, persistence, service by LifeXplorer · Pull Request #6979 · comet-ml/opik

LifeXplorer · 2026-06-05T13:53:57Z

Details

PR 1 of 7 splitting #6900 (MCP OAuth 2.1 Authorization Server) into smaller, shippable chunks per review feedback — working inner-foundations outward, schema first, deployment last. #6900 stays open as the full reference.

This PR is the shared inner foundation every OAuth resource depends on: schema + config + domain types + persistence + token-lifecycle service. It has no REST surface, no guicey bundle, no OpikApplication wiring — nothing is exposed and there is zero behavior change. The feature is gated by MCP_OAUTH_ENABLED (defaults false) and stays inert until the full chain lands.

What's in the box

Layer	Files
Schema	Liquibase migration `000080` — `mcp_oauth_clients` / `_codes` / `_tokens` on `db-app-state` (no seeded clients; all MCP hosts register via DCR in a later chunk)
Config	`McpOAuthConfig` (env-gated by `MCP_OAUTH_ENABLED`) + `config.yml` `mcpOAuth:` block + `OpikConfiguration.mcpOAuth` field
Constants / models	`OAuthConstants`, `McpOAuthClient`, `McpOAuthCode`, `McpOAuthToken`, `McpOAuthTokens` (token utils), `ValidatedToken`, `CreateOAuthCodeCommand`, `TokenResponse`, `ClientRegistrationRequest`
Persistence	JDBI DAOs `McpOAuthClientDAO` / `McpOAuthCodeDAO` / `McpOAuthTokenDAO` — atomic mark-used, refresh rotation, revoke-family
Strategy + service	`OAuthClientStrategy` seam + `DbOAuthClientStrategy` + `OAuthClientService`; `McpOAuthService` — code exchange (PKCE/S256 verify), refresh rotation w/ reuse detection + grace, revoke, validate

Deliberately deferred

MutableJobConfiguration switch on OpikConfiguration and the config.yml jobs.mcpOAuthScrubCron entry → move with the scrub job (PR 6), which is the only thing that needs them.
All REST resources, the McpOAuthBundle kill-switch, AuthFilter/AuthService integration, tests, and helm/nginx deployment → later chunks.

The split (7 PRs)

Foundations ← this PR
Metadata endpoint (/.well-known/oauth-authorization-server) + guicey bundle wiring
Authorize + consent (/oauth/authorize) + AuthService workspace resolution
Token + revoke (/oauth/token, /oauth/revoke)
Dynamic client registration (/oauth/register, RFC 7591)
Data-API bearer integration (AuthFilter) + validator (/opik/auth-oauth) + scrub job + E2E
Deployment (helm/nginx)

Change checklist

User facing
Documentation update

Neither applies: this chunk has no REST surface and zero behavior change — nothing is user-facing and there is nothing to document until the endpoints land in later PRs.

Testing

mvn -o compile — green. Only out-of-set dependencies (IdGenerator, SetFlatArgumentFactory) already exist on main.
No tests in this chunk by design — OAuth test suites land with their resources in PRs 3–6.

Issues

Jira: OPIK-6666
Full reference: [OPIK-6666] [BE] feat: MCP OAuth 2.1 Authorization Server #6900
Companion / dependency (lands before the feature is enabled): comet-ml/comet-backend#5569

Documentation

N/A for this chunk — no user-facing surface. End-user OAuth setup/usage docs land with the deployment PR (7/7).

🤖 Generated with Claude Code

…main, persistence, service PR 1 of 7 splitting #6900 (MCP OAuth 2.1 Authorization Server) into shippable chunks per review. This is the shared inner foundation that every OAuth resource depends on — no REST surface, no app wiring, no behavior change. Includes: - Liquibase migration 000080: mcp_oauth_clients/_codes/_tokens on db-app-state - McpOAuthConfig (env-gated by MCP_OAUTH_ENABLED) + config.yml mcpOAuth block + OpikConfiguration.mcpOAuth field - Domain models + token utils (clients, codes, tokens, ValidatedToken, etc.) - JDBI DAOs (clients/codes/tokens) with atomic mark-used, rotation, revoke-family - OAuthClientStrategy seam + DbOAuthClientStrategy + OAuthClientService - McpOAuthService — code exchange (PKCE), refresh rotation w/ reuse detection, revoke, validate Deferred to PR 6 (scrub job): the MutableJobConfiguration switch and the config.yml jobs.mcpOAuthScrubCron entry, which only the scrub job needs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

andrescrz

Many of the comments are mentioned once, but they apply to other parts of the code base.

I still recommend breaking this down into smaller chunks, to progress and deliver faster.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…IdGenerator Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-07T20:13:34Z

Backend Tests - Integration Group 7

1 487 tests ±0 1 487 ✅ ±0 6m 24s ⏱️ -18s
20 suites ±0 0 💤 ±0
20 files ±0 0 ❌ ±0

Results for commit a7a015e. ± Comparison against base commit e276974.

♻️ This comment has been updated with latest results.

…ct mapper Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…on the record Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…apper Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…kenResponse Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@nonnull

code_challenge is NOT NULL in the schema and PKCE is mandatory, so the value cannot be null here; annotate the params @nonnull instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…hing Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@min

…dation Defaults were duplicated between McpOAuthConfig and config.yml. Remove the Java-side defaults (durations, rate limit, enabled) so they live only in YAML, and enforce presence via @NotNull / @min so a missing value fails fast at boot. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

andrescrz

The PR mostly LGTM now.

There's still one blocking comment in the MySQL table definitions regarding the type of client_id fields. We cannot change the migrations one pushed, I'd rather it address it now.

The rest of comments are optional. Many of them are nice to have, so I recommend tackling them as you have to send a new revision anyway.

Many comments are reflected once, but applies to multiple places (like record validations).

Let's do a final iteration and this should be good to go.

@nonnull

Replace the hand-written builders in McpOAuthService with a MapStruct mapper (toCode/toToken/toRotatedToken), building each record complete in one pass to respect the @nonnull record guards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@define

Merge revoke and revokeFamily into a single revokeBy query that swaps the WHERE column via @define; keep both as thin default delegators passing a hardcoded column literal. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The clients-table primary key follows the table-local id convention; the client_id foreign keys in mcp_oauth_codes/mcp_oauth_tokens are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@jsonvalue

Implement HasValue with @jsonvalue values and register an AbstractEnumColumnMapper so persistence/serialization no longer rely on the enum constant name. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

andrescrz

LGTM.

This was along and complex piece of work, with many moving pieces. But the implementation looks clean and solid.

Well done & thanks for putting it together!

LifeXplorer requested a review from a team as a code owner June 5, 2026 13:53

github-actions Bot assigned LifeXplorer Jun 5, 2026

github-actions Bot added java Pull requests that update Java code Backend labels Jun 5, 2026

baz-reviewer Bot reviewed Jun 5, 2026

View reviewed changes

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/McpOAuthTokenDAO.java Outdated

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/McpOAuthService.java

Merge branch 'main' into avinahradau/OPIK-6666-oauth-as-chunked-1

9f31d46

LifeXplorer requested a review from andrescrz June 5, 2026 15:09

andrescrz requested changes Jun 5, 2026

View reviewed changes

OPIK-6666 updated DB columns size

7d088dd

baz-reviewer Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread ...kend/src/main/resources/liquibase/db-app-state/migrations/000080_create_mcp_oauth_tables.sql Outdated

Comment thread ...kend/src/main/resources/liquibase/db-app-state/migrations/000080_create_mcp_oauth_tables.sql

LifeXplorer added 3 commits June 7, 2026 19:36

OPIK-6666 remove unused revoke and getAll methods

dfe900b

OPIK-6666 remove unused fields at mcp_oauth_clients

f8c84e5

OPIK-6666 add id as PK for code and token tables

986c5c7

baz-reviewer Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/McpOAuthService.java Outdated

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/McpOAuthService.java Outdated

LifeXplorer and others added 7 commits June 7, 2026 20:15

OPIK-6666 switch to rotateFromId

3b931fe

OPIK-6666 propagate mcpOAuth config to config-test.yml

5cbbd2a

OPIK-6666 add toBuilder to ClientRegistrationRequest

2672851

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 add bean validation annotations to ClientRegistrationRequest

c1de3f6

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 update comment

28cacc0

OPIK-6666 omit null fields from TokenResponse

9f9a681

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 declare snake_case naming on ClientRegistrationRequest

4c9d24a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot added the tests Including test files, or tests related like configuration. label Jun 7, 2026

OPIK-6666 use random UUIDv4 for mcpoauth ids instead of time-ordered …

b3fdf11

…IdGenerator Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

LifeXplorer and others added 5 commits June 8, 2026 09:01

OPIK-6666 map ClientRegistrationRequest to McpOAuthClient via MapStru…

54c52a8

…ct mapper Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 move client registration validation to Jakarta constraints …

f296e2a

…on the record Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 update java doc

4458484

OPIK-6666 use text blocks for mcpoauth DAO SQL statements

60f0e0a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 return Optional from findActiveById and drop fetchActive wr…

1f314d4

…apper Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

LifeXplorer and others added 9 commits June 8, 2026 09:47

OPIK-6666 favour builders over constructors for ValidatedToken and To…

c1af97d

…kenResponse Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 document US_ASCII charset rationale in PKCE verification

fdd3c47

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 update java doc

3ba1b8c

OPIK-6666 drop redundant codeChallenge null check in verifyPkce

3909363

code_challenge is NOT NULL in the schema and PKCE is mandatory, so the value cannot be null here; annotate the params @nonnull instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 use more specific opik_mcp_ token prefixes

e3ebe60

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

OPIK-6666 use SecureRandom factory method

5c1f4b0

OPIK-6666 reuse DigestUtils.sha256Hex instead of inlining SHA-256 has…

bacdf8d

…hing Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

refactor(mcpoauth): co-locate OAuthClientStrategy with its single impl

d577854

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

baz-reviewer Bot approved these changes Jun 8, 2026

View reviewed changes

LifeXplorer requested a review from andrescrz June 8, 2026 09:38

baz-reviewer Bot approved these changes Jun 8, 2026

View reviewed changes

Merge branch 'main' into avinahradau/OPIK-6666-oauth-as-chunked-1

a380a08

LifeXplorer mentioned this pull request Jun 8, 2026

[OPIK-6666] [BE] feat: MCP OAuth metadata endpoint + bundle wiring (PR 2/7) #6993

Open

2 tasks

andrescrz reviewed Jun 9, 2026

View reviewed changes

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/RevokedReason.java Outdated

LifeXplorer and others added 8 commits June 9, 2026 11:43

OPIK-6666 update javadocs

32f1022

OPIK-6666 adding NonNulls

29ebbed

OPIK-6666 review updates

98022e7

refactor(mcpoauth): rename mcp_oauth_clients PK to id

d886067

The clients-table primary key follows the table-local id convention; the client_id foreign keys in mcp_oauth_codes/mcp_oauth_tokens are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'main' into avinahradau/OPIK-6666-oauth-as-chunked-1

08d0ecb

baz-reviewer Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread apps/opik-backend/src/main/java/com/comet/opik/domain/mcpoauth/ClientRegistrationRequest.java

LifeXplorer requested a review from andrescrz June 9, 2026 12:47

baz-reviewer Bot approved these changes Jun 9, 2026

View reviewed changes

andrescrz approved these changes Jun 9, 2026

View reviewed changes

LifeXplorer merged commit d12bd39 into main Jun 9, 2026
70 checks passed

LifeXplorer deleted the avinahradau/OPIK-6666-oauth-as-chunked-1 branch June 9, 2026 13:10

Conversation

LifeXplorer commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Details

What's in the box

Deliberately deferred

The split (7 PRs)

Change checklist

Testing

Issues

Documentation

Uh oh!

Uh oh!

Uh oh!

andrescrz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backend Tests - Integration Group 7

Uh oh!

andrescrz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrescrz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LifeXplorer commented Jun 5, 2026 •

edited

Loading

github-actions Bot commented Jun 7, 2026 •

edited

Loading