OAuth 2.1 authorization server for token-free client auth (MCP & browser extension)

[bdshadow]

1. Problem

Every non-webapp client that talks to a Tolgee server authenticates with a static, long-lived secret, a Project API Key (PAK) or Personal Access Token (PAT) sent as the X-API-Key header (AuthenticationFilter.kt). The user generates that key in the UI, copies it, and pastes it into the client.

The reason this matters most is community translation. With public projects, a contributor is a logged-in non-member who gets an implicit "community floor" of permissions (view, suggest, comment) on a public project, and there is no anonymous access. To translate in-context, that external person's browser extension needs a credential, and we cannot hand a stranger a project API key (a PAK is bounded to a member's own project access). OAuth is what lets an outside contributor authorize the extension with exactly their community-level access. This is the critical path.

The same paste-a-static-key friction hits our other headless clients:

• Browser extension and SDK (in-context editing, @tolgee/web and tolgee/browser-extension): the user pastes a key that the extension stores and the SDK replays as X-API-Key.
• MCP server (/mcp/developer, in the official MCP registry): users paste a PAK/PAT into MCP client config, landing in plaintext JSON on disk, out of step with the MCP OAuth 2.1 spec. Secondary priority, a power-user convenience rather than the driver.
• Tolgee CLI (tolgee/tolgee-cli): same paste-a-token model; users expect the seamless "open browser, approve, logged in" flow.

---

2. Appetite

2w

---

3. Solution

Make the Tolgee platform an OAuth 2.1 authorization server using spring-security-oauth2-authorization-server, exposing Authorization Code + PKCE so a client redirects the user to Tolgee, the user consents to a listed set of access, and the client receives a short-lived access token (plus refresh token) instead of a pasted key. All our clients are public clients (no secret); PKCE replaces the secret.

Core mechanics:

• A dedicated SecurityFilterChain for the authz-server endpoints (/oauth2/authorize, /oauth2/token, .well-known/*), coexisting with the existing stateless chain.
• Reuse the JWT stack (JwtService) as the access-token format so AuthenticationFilter's existing Bearer path validates OAuth tokens. Tokens are audience-bound (RFC 8707): a token minted for MCP carries aud = <MCP canonical URI> and is rejected by the REST API, and vice versa.
• The scope model is the existing Scope enum wire values (translations.suggest, translation-suggestions.manage, translation-comments.add, and so on). Effective access is expand(token.scopes) intersected with expand(user's live project scopes), evaluated per request. This is already exactly what SecurityService.getCurrentPermittedScopes does for PAKs. The token only narrows; losing a project or leaving the org kills access immediately.
• Client registration. Our own clients (extension, CLI): pre-registered public clients with a fixed client_id and redirect URIs (seeded rows, giving the extension a real chrome-extension:// anchor and branded consent). Unknown third-party MCP clients: Client ID Metadata Documents (CIMD), where the client's client_id is an HTTPS URL we fetch and validate. CIMD is spec-preferred and supported by the MCP clients we target (Claude Code, Claude Desktop, VS Code Copilot). Implemented as a custom RegisteredClientRepository, since it is not in SAS. DCR is not implemented in v1 (see No-Goes).

Extension and SDK (the critical path, and a cross-repo change). This is three repos (platform, tolgee/browser-extension, and @tolgee/web pinned on customer sites), not a one-liner. It needs:

• a PAK-vs-OAuth discriminator so the SDK picks the right header;
• a Bearer branch in @tolgee/web's client.ts (today it is unconditionally X-API-Key);
• token lifecycle the SDK has never had: 401, ask the extension, refresh, retry;
• capability negotiation via TOLGEE_READY (absence means an old SDK), so we carry both the X-API-Key and Bearer paths indefinitely;
• the refresh token stays in extension storage; the page/SDK only ever receives short-lived access tokens (page sessionStorage is XSS-reachable).

Scope and consent decisions (load-bearing, named now rather than left to the spike):

• Capabilities live in scope; the project set lives in a custom claim, since the client doesn't know project IDs before it is authorized.
• "All projects" is a sentinel (including future projects), never an expanded list, otherwise tokens blow past header limits for big orgs and users re-authorize on every new project. GitHub's wording is "all repositories, including future ones".
• A client that knows the project (Figma, the extension) may hint one; consent pre-selects and marks it required, other accessible projects optional. The server validates the user actually holds those scopes on the hint, so it can't leak IDs or nudge access.
• Re-consent / step-up is first-class, not just first login; it maps onto the MCP spec's insufficient_scope step-up flow.
• Effective access is evaluated per request (token intersected with live permissions, per the core mechanics above).
• Org-level operations don't fit a per-project selector: v1 covers project scopes plus "all projects"; org-level ops get their own consent scope or are a v1 no-go.

Other clients:

• MCP: Protected Resource Metadata (RFC 9728) on /mcp/developer, RFC 8707 audience, RFC 9207 issuer, so spec-compliant clients discover and run the flow, with CIMD for the ones we don't pre-register.
• CLI: seamless login via loopback redirect (http://127.0.0.1:<port>) plus PKCE. Keeps --api-key for CI and back-compat.

Cross-cutting:

• Connected apps: persist authorizations and revoke a single app, largely free from SAS's OAuth2AuthorizationService. The durable grant/refresh/consent store lives in Postgres (built-in JDBC); Redis (optional) is used only for ephemeral TTL data (authorization codes, a revocation denylist), never the system of record.
• Signing keys: today's JWT uses a symmetric HMAC secret auto-generated at boot. OAuth needs an asymmetric keypair plus a JWKS endpoint (external verification), persisted so restarts/replicas don't invalidate tokens, with a rotation-with-overlap story.
• Token lifetimes: short access TTL; refresh rotation with reuse detection plus a grace window tolerating near-simultaneous refresh; a defined grant-invalidation trigger.
• PAK/PAT stay for CI, scripts, and machine-to-machine (see No-Goes).

---

4. Basic Drawings

---

5. Rabbit Holes

• Scope-to-permission mapping: expose the Scope enum as OAuth scopes and reuse the existing getCurrentPermittedScopes intersection, including the public-project community floor (derived server-side per request, independent of token scopes). The consent UI reuses the permissions-dialog content plus a project selector ("all projects").
• CIMD implementation (in scope): not in Spring Authorization Server, so we build a custom RegisteredClientRepository that resolves the URL-form client_id, fetches the metadata doc, validates client_id against redirect_uris, advertises client_id_metadata_document_supported in AS metadata, invalidates consents when a client's redirect_uris change, and hardens the outbound fetch against SSRF (allow-list, no internal IPs, size and timeout limits) with caching. This is the security-critical surface of the cycle.
• Extension version negotiation: customer sites pin @tolgee/web; an old SDK reading an OAuth token as X-API-Key gets a 401. A capability flag on TOLGEE_READY, both paths carried for a long time.
• Refresh-token rotation races: clients refresh proactively before expiry, so rotation must tolerate near-simultaneous attempts without tripping reuse-detection.
• Audience binding (RFC 8707): JwtService emits one fixed audience today; OAuth needs a per-resource aud and rejection of wrong-audience tokens.
• Self-hosted keys and discovery: persisted asymmetric keys, JWKS, issuer and canonical URIs, zero-config on a fresh instance, correct behind reverse proxies (external URL is not the internal URL).
• Two filter chains on Security 7: the authz-server chain coexisting with the stateless chain on the freshly-migrated chore: migrate to Spring Boot 4 #3804 baseline.

---

6. No-Goes

• Not full/unified session management. Connected-apps plus per-OAuth-grant revocation is in; revoking the webapp's own stateless JWT sessions, "log out everywhere", or a unified view across JWT/PAK/PAT/OAuth is a separate subsystem and a follow-up.
• DCR (RFC 7591) deferred. CIMD covers the MCP clients we target; DCR is a fast-follow only if we hit a DCR-only client. Avoids building two registration paths.
• Figma plugin deferred. Its iframe can't do a redirect (null origin); the right answer is the device authorization grant (RFC 8628), and a large Figma refactor is landing soon. Postponed to a later version to avoid rework; rationale captured so it isn't re-litigated.
• Device grant deferred, unless a headless/SSH/container CLI case forces it earlier.
• Not removing PAK/PAT. They stay for CI, scripts, and machine-to-machine. Additive.
• Not the client_credentials grant. PAK already covers headless machine-to-machine.
• Not a general-purpose IdP. No "Login with Tolgee" for third parties, and no change to Tolgee's SSO-client role.
• No Redis-backed system of record for grants. Postgres stays authoritative.
• Org-level operations out of v1 unless the scope model lands cleanly.

---

7. Success Criteria

• An external community contributor authorizes the browser extension on a public project via redirect and consent, and suggests a translation, with no key pasted. This is the headline.
• The extension logs in via redirect and consent for members too; no manual key entry.
• The CLI logs in via the browser (open, approve, done); --api-key still works for CI.
• A real MCP client (Claude Desktop, Cursor) connects to /mcp/developer via redirect and consent, nothing in plaintext JSON.
• An unknown third-party MCP client authorizes via CIMD (URL-form client_id, no pasted key, no pre-registration on our side), and a client presenting a client_id whose metadata doesn't list its redirect_uri is rejected.
• Issued tokens carry exactly the consented scope, and effective access is the token intersected with live permissions evaluated per request (losing a project or leaving the org revokes immediately).
• Audience binding holds: an MCP token is rejected by the REST API and vice versa.
• A user can see connected apps and revoke one without affecting others.
• Works on a fresh self-hosted instance with no config, including persisted signing keys (restarts/replicas don't log everyone out).
• PAK/PAT auth continues to work unchanged.

Scopes

MUST:

• OAuth server core — Click connect in an app, log in in the browser, and get a short-lived token instead of a pasted key. Demoable with curl/Postman against the endpoint that already accepts Bearer.

• Scope model & token shape — The token carries exactly what was approved: which actions, on which project. ("All projects" sentinel exists but is for owner clients, not community.)

• Live permission enforcement — The moment someone loses access to a project, their token stops working there.

• Audience binding — A token issued for one thing can't be used against another (foreign-audience token is rejected).

• Consent screen — When an app asks to connect, the person sees a plain summary of what it will be able to do and clicks Allow or Deny. Project is pre-filled from context, not picked.

• Connected apps & revocation — See the apps you've connected and disconnect any of them for real.

• Stay signed in — Sign in once and stay signed in; the token renews silently.

• SDK — OAuth prep (@tolgee/web) — The SDK can speak OAuth, so any app or plugin on it can log in without a key. (Project comes from page config, not decoded from the key.)

• Chrome plugin — path prep — The plugin's sign-in path is wired and verified end to end. (The page's known project survives the token swap.)

• MCP client (+ CIMD) — An AI tool (Claude, VS Code, Cursor) connects by logging in, with no key in a config file, and works across your projects.

• Tolgee CLI — Sign in with one command via the browser and the CLI just works; key option stays for CI.

OPTIONAL:

• Figma plugin

[JanCizmar]

It would be awesome if we also include this seamless flow when the client forwards you to browser and then automatically logs you in when you approve in the browser (like Claude and other CLI tools have it).

[Anty0]

A few notes from reading the pitch:

• I suspect the pitch is for OAuth without a client secret -> no client registration, just a basic public client flow. That makes it much simpler, but let's see if it will be enough.
• The connected-app/revocation part also sounds like the start of session management, which makes the one-week scope pretty tight. We should probably follow up with full session management soon, too.
• I’d vote to make this a full two-week cycle and include the Tolgee CLI integration. Even the current scope feels too large for one week.
• For the consent UI, I’d reuse the existing permissions-dialog content, with a project selector at the top, including an “all projects” option. Or do you plan a different UI for this?

[bdshadow]

@Anty0 thank you for the notes!

1. No client secret / no registration

Correct that it's a public-client flow with no client secret - all three targets (MCP client, browser extension, CLI) run on the user's device and can't keep a secret, so PKCE replaces the secret. But "no secret" and "no registration" are separate axes: a public client still needs a client_id + registered redirect_uris, otherwise we open an open-redirect / token-theft hole. The current MCP auth spec requires a client_id via one of three mechanisms, in priority order: Client ID Metadata Documents (CIMD, URL-as-client_id, new, SHOULD), pre-registration, or DCR (now deprecated/back-compat).

So it splits by client:

• Browser extension + CLI: we own them -> pre-registered public clients (fixedclient_id + redirect URIs). No registration endpoint - this is the simple flow you're describing.
• Arbitrary MCP clients (Claude Desktop, Cursor, …): we don't know them upfront, so we can't pre-register. Two options, neither built into Spring Authorization Server — this is the registration decision:
  • DCR: Spring supports it out of the box, but it's a public write endpoint (abuse/DoS surface) and it's the mechanism the MCP spec just deprecated.
  • Roll our own CIMD: the spec-preferred path, no public write endpoint. Not in the library (spring-security#18375 is still open), but it's implementable as a custom RegisteredClientRepository that resolves the URL-form client_id and fetches its metadata doc - the spring maintainer has a reference impl in a demo repo. Catch: we'd own the security-critical parts that the reference is missing (client_id <->redirect_uris validation, client_id_metadata_document_supported metadata flag, consent invalidation when redirect_uris change).

One more spec constraint that feeds the scope work: tokens must be audience-bound to the MCP server (resource param, RFC 8707), so "one generic token reused everywhere" is out.

2. Connected apps / session management

I'd split this in two:

• Grant persistence + per-app revocation ("connected apps") isn't really extra scope. The moment we issue refresh tokens we must persist the authorization and be able to revoke it, and Spring Authorization Server gives that essentially for free via OAuth2AuthorizationService (+ a small revoke screen on top). Minimal connected-apps stays in.
• Full/unified session management (revoking the webapp's own sessions, "log out everywhere", one view across JWT/PAK/PAT/OAuth) is a much bigger thing - our webapp auth is stateless JWT with no server-side session registry today, so that's a new subsystem. Agree with you: follow-up pitch, explicit No-Go here.

3. Consent UI

+1 to reusing the permissions-dialog content with a project selector + an "all projects" option - that's exactly the surface the scope<->permission mapping produces, no separate UI needed. Let's go with that.

4. Appetite: 2 weeks

Agree, 1 week is too tight. I'll update it

[bdshadow]

updated the pitch according to the comments and internal discussion with @Anty0 and the team

[JanCizmar]

Hey! I have invested my Saturday's morning into this and I have to say it's a solid Rabbit hole. 😃 🐇 Here's my points...

Good pitch, I'm on board with the direction. Few things I'd want nailed down before the spike starts.

Where we are

We're making Tolgee an OAuth 2.1 authz server so clients stop pasting static keys. Two weeks, on top of the Spring Boot 4 branch.

Worth being explicit about why this matters to us, because it shapes the priorities. The pitch reads as three clients with paste friction and leans heavily on MCP. But the reason we need this is mainly community translations. If someone outside the team is going to translate our app in context, we can't hand them a project API key. So the extension and SDK path is the critical path here, not a nice extra on top of the MCP work.

What's not settled

Three things, in order of how much they'd hurt if we find them in week two.

The extension work is described in one line but it's a cross repo protocol change. "Broaden the sessionStorage credential contract" sounds like adding a key. What it actually needs:

• a discriminator so the SDK knows whether it got a PAK or an OAuth token, they go in different headers
• a Bearer branch in client.ts, today line 85 is unconditionally X-API-Key
• token lifecycle in an SDK that has never had any: 401, ask the extension, refresh, retry. That's a new message round trip, and the refresh token has to stay extension side
• version negotiation. Customer sites pin their @tolgee/web version, often on production. An older SDK reading an OAuth token out of __tolgee_apiKey will send it as X-API-Key and get a 401. TOLGEE_READY gives us somewhere to put a capability flag, but absence means old, so we carry both paths for a long time

Given this is the path we actually care about, I'd rather it were scoped properly than discovered mid cycle.

The scope and consent design is deferred to the spike, but some decisions are load bearing and worth naming now.

Projects can't live in the scope string, the client doesn't know our project IDs before it's authorized. So capabilities in scope, project set in a custom claim. "All projects" has to be a sentinel rather than an expanded list, otherwise tokens blow past header size limits for big orgs and users re-authorize every time they create a project. GitHub's wording is "all repositories, including future ones", worth copying.

Some clients do know the project upfront though, Figma has it in settings and the extension can too. So let the client hint one: consent pre-selects it and marks it required, other projects the user has access to are optional. The server validates the user actually has those scopes on the hinted project, so the hint can never leak IDs or nudge access. And we need a re-consent path, not just first login, someone working across Figma documents will hit "my token doesn't cover this project" regularly.

The rule underneath all of it: effective permission is token scope intersected with live permissions, evaluated per request. The token narrows, it never grants. So losing a project or leaving the org kills access immediately rather than at expiry. Success criteria say "verifiably mapped" but not when it's evaluated, and that's the whole difference.

Org roles get one mention and then disappear. Org level operations don't fit a per-project selector at all.

The Figma plugin has the same problem and isn't in the pitch. It pastes a PAK and keeps it in clientStorage, same story as the others.

It also can't do a redirect flow at all. The plugin iframe has a null origin and openExternal doesn't call back, so there's nowhere to redirect to. The clean answer is the device authorization grant, RFC 8628, which SAS supports natively: show a code, user approves in a real browser, plugin polls the standard token endpoint. No extra service, and self-hosted works unchanged.

I'd put it in this cycle rather than defer it. It's a second grant type on machinery we're already building, and it's what gives us a foundation for every client shape rather than just the ones with a redirect target. It also covers headless CLI, SSH and containers, where loopback can't work.

Smaller things

• Token lifetimes are missing entirely. Access TTL, refresh rotation with reuse detection, what invalidates a grant. Claude refreshes reactively on 401 and proactively up to five minutes before expiry, so rotation has to tolerate near simultaneous attempts.
• Signing keys on self-hosted. If we generate at boot, every restart logs everyone out and it gets reported as a bug. Persisted keys, JWKS, rotation story. Fits under the "fresh instance, no config" criterion.
• CLI keeps --api-key for backward compatibility and CI. Worth stating in the pitch so it doesn't read as a migration.

[bdshadow]

@JanCizmar thank you for the input

Community translation is the real driver. Agreed, reprioritizing the pitch around it. Confirmed in code: a contributor is a logged-in non-member who gets the community floor (view, suggest, comment) on a public project, and there is no anonymous access, so the extension genuinely needs a token and it can't be a PAK. Extension/SDK becomes the critical path; MCP drops to secondary.

Extension is a cross-repo protocol change. 100%, and it's actually three repos (platform, browser-extension, and @tolgee/web pinned on customer sites). Giving it its own scope: a PAK-vs-OAuth discriminator (different header), a Bearer branch in client.ts, token lifecycle (401, ask extension, refresh, retry), and TOLGEE_READY capability negotiation with both paths carried indefinitely. One addition: the refresh token stays in extension storage, and the page/SDK only ever gets short-lived access tokens (sessionStorage is XSS-reachable).

Load-bearing scope and consent decisions. Agreed, promoting them out of the spike and naming them in the Solution: capabilities in scope plus the project set in a claim, "all projects" as a sentinel including future ones (borrowing GitHub's wording), a server-validated project hint, and re-consent / step-up (which maps straight onto the MCP spec's insufficient_scope step-up flow). The "effective = token intersected with live permissions, per request" rule is already the live model (getCurrentPermittedScopes does exactly that intersection today), so I'll state it as a criterion including when it is evaluated. Org-level ops: v1 covers project scopes plus "all projects"; org-level either gets its own consent scope or is a v1 no-go.

Figma and the device grant. You're right that it can't redirect and that RFC 8628 is the clean answer. But splitting the grant type from the plugin client: a big Figma refactor is landing soon, so building the plugin integration now is rework. I'd postpone the Figma client to a later version and capture the device grant as a named follow-up (with the 8628 rationale, so it isn't re-litigated), unless a headless/SSH CLI case needs it sooner.

Registration: I want CIMD in v1. The MCP clients we target already support it (Claude Code, Claude Desktop, VS Code Copilot; Cursor on the roadmap), and Anthropic recommends it as the default, so it connects real clients today. That means we build a custom RegisteredClientRepository for CIMD (it isn't in Spring Authorization Server), and DCR stays out of v1 as a fast-follow only if we hit a DCR-only client. No pre-registration for third parties, no open registration endpoint.

Smaller things, all in:

• Token lifetimes: short access TTL, refresh rotation with reuse detection plus a grace window for near-simultaneous refresh (your proactive-refresh point), and a defined grant-invalidation trigger.
• Signing keys: today it's a symmetric HMAC secret auto-generated at boot. OAuth needs asymmetric keys plus JWKS for external verification, persisted so restarts/replicas don't log everyone out, with a rotation story. Lands under "fresh instance, no config".
• CLI keeps --api-key for CI and back-compat, stated so it doesn't read as a migration.