feat(oauth): configurable Basic username claim (#152)

Add oauth.username_claim (--oauth-username-claim / MCP_OAUTH_USERNAME_CLAIM)
to select which JWT claim becomes the ClickHouse Basic-auth username on the
ch-jwt-verify sidecar path. Unset keeps today's behavior (email + namespaced
*/email fallback); when set, basicUsernameFromJWT does a strict top-level
lookup of that single claim via oauth.UsernameFromExtra and fails closed on a
missing/empty/non-string value, naming the claim in the error. The value is an
unverified hint only — CH/sidecar still validate the JWT. Bearer path and
role_claim/role_filter are unchanged.

Bumps go-mcp-oauth-sdk to the release carrying UsernameClaim + UsernameFromExtra.
Docs: docs/oauth_authorization.md + helm values.

Closes #152

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SV1MFJRKvA1zWsacpeieoE

Author: BorisTyshkevich

docs/oauth_authorization.md

@@ -75,6 +75,18 @@ user-vs-claim match.
   WITH http SERVER 'ch_jwt_verify' SCHEME 'BASIC'`.
 - Forces HTTP protocol on the driver.
 
+By default the Basic username is the JWT `email` claim (with a namespaced
+`*/email` fallback for Auth0 DCR tokens). Set **`oauth.username_claim`** to
+use a different claim (`username`, `preferred_username`, `sub`, …) when your
+ClickHouse users are provisioned from that claim. When set, MCP does a strict
+top-level lookup of that single claim and **fails closed** on a
+missing/empty/non-string value — it never silently falls back to email or
+another identity. An explicit `username_claim: email` is therefore strict and
+does *not* do the namespaced fallback; leave it unset if you rely on that.
+**`oauth.username_claim` must match the sidecar's `identity.username_claim`**
+(see below) — a mismatch fails authentication. The value is an unverified
+hint only; the sidecar still validates the JWT and the user-vs-claim match.
+
 ### Detection logic
 
 On the first authenticated request to `host:port`, MCP tries Bearer. If
@@ -167,6 +179,12 @@ identity:
   allowed_email_domains: ["example.com"]
 ```
 
+The sidecar's `identity.username_claim` here **must match** MCP's
+`oauth.username_claim` (default `email`). MCP puts that claim's value in the
+Basic username; the sidecar re-reads the same claim from the verified token
+and rejects the request if they disagree. If you point the sidecar at a
+non-email claim, set MCP's `oauth.username_claim` to the same claim.
+
 ## ClickHouse `token_processors` (Bearer auth path)
 
 If your ClickHouse uses `token_processors`, altinity-mcp will detect
@@ -283,6 +301,13 @@ server:
     role_claim: ""        # e.g. "https://clickhouse/roles"
     role_filter: ""       # optional; e.g. "^anon_" (empty = activate all claim roles)
 
+    # JWT claim used as the ClickHouse Basic-auth username on the sidecar path.
+    # Empty = default `email` claim + namespaced */email fallback. When set, a
+    # strict top-level lookup of this single claim is used and a missing/empty/
+    # non-string value fails closed. Must match the sidecar's
+    # identity.username_claim. Applies only to the Basic path, not Bearer.
+    username_claim: ""    # e.g. "username", "preferred_username", "sub"
+
     # Token lifetimes (broker mode)
     access_token_ttl_seconds: 3600
     refresh_token_ttl_seconds: 2592000   # 30 d
@@ -313,6 +338,7 @@ server:
 | `upstream_offline_access` | Request `offline_access` upstream so the IdP consent screen offers long-lived sessions. Default `false`. |
 | `role_claim` | JWT claim holding a JSON array of ClickHouse role names to activate per request (e.g. `https://clickhouse/roles`). Empty disables. Read from the validated token's namespaced/custom claims. |
 | `role_filter` | **Optional** regex narrowing which `role_claim` roles are activated (e.g. `_mcp$`). When empty, **all** roles in the claim are activated (the IdP curates the set; CH re-validates the token and enforces grants). Only ever narrows; an empty *resolved* set (claim absent/empty, or filter matched nothing) fails closed — request denied, no fallback to the full grant. HTTP protocol only; applies in both Bearer and Basic/sidecar paths. **Anchor it** (`^…`/`…$`) — it's a partial match, so an unanchored `anon` would also match `not_anon_real`. |
+| `username_claim` | JWT claim used as the ClickHouse Basic-auth username on the `ch-jwt-verify` sidecar path. Empty (default) = `email` claim with a namespaced `*/email` fallback. When set (e.g. `username`, `preferred_username`, `sub`), a strict top-level lookup of that single claim is used and a missing/empty/non-string value **fails closed** — never falling back to another identity. An explicit `email` is strict (no namespaced fallback). Unverified hint only (CH/sidecar still validate). **Must match the sidecar's `identity.username_claim`.** Basic path only; no effect on Bearer. |
 
 ## Provider-specific setup
 

go.mod

@@ -20,7 +20,7 @@ require golang.org/x/crypto v0.53.0 // indirect
 
 require (
 	github.com/ClickHouse/ch-go v0.73.0 // indirect
-	github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260615173123-b30b0552560b
+	github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260708140922-cd8667cc7d14
 	github.com/andybalholm/brotli v1.2.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect

go.sum

@@ -4,8 +4,8 @@ github.com/ClickHouse/ch-go v0.73.0 h1:jsHiGRbQ3sz+gekvDFJF29LWDo5dzbJm5s1h8TWVP
 github.com/ClickHouse/ch-go v0.73.0/go.mod h1:wkFIxrqlXeRJ9cn3r5Fz5Qen9jl5aTMPuGZeuJpANNY=
 github.com/ClickHouse/clickhouse-go/v2 v2.47.0 h1:ZDAzrnKSOPTIsm4tdUNfrii2yc8dk4SVRLC77BR7Z5Q=
 github.com/ClickHouse/clickhouse-go/v2 v2.47.0/go.mod h1:sPj7C7UYQ2MWHcfX+4eGN6nwnCqwUKfgO6PcwKpd6K8=
-github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260615173123-b30b0552560b h1:2CHdIO/kNhgq077KkhReHLonr/HliNHit8wmKq6wDcU=
-github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260615173123-b30b0552560b/go.mod h1:yLgv0x586vIzPB5JaA6DkqQsSe4PLRT3PhU2iHO7qsI=
+github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260708140922-cd8667cc7d14 h1:qtt8C3izTL9MYCd2fJ3r+PBycjPP3QapQVjveS1wEcA=
+github.com/altinity/go-mcp-oauth-sdk v0.1.1-0.20260708140922-cd8667cc7d14/go.mod h1:Ad/Ri3RM1yYmE/huozKXv/FSQWq2UEj5gmmnHeLHRk4=
 github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
 github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=

helm/altinity-mcp/values.yaml

@@ -228,6 +228,14 @@ config:
       # the full grant. Anchor it (^…/…$): it is a partial match, so an
       # unanchored "anon" would also match "not_anon_real".
       role_filter: ""
+      # -- JWT claim used as the ClickHouse Basic-auth username on the
+      # ch-jwt-verify sidecar path (#152). Empty (default) uses the `email`
+      # claim with a namespaced `*/email` fallback. When set (e.g. "username",
+      # "preferred_username", "sub"), a strict top-level lookup of that single
+      # claim is used and a missing/empty/non-string value fails closed rather
+      # than falling back to another identity. Must match the sidecar's
+      # identity.username_claim. Applies only to the Basic path, not Bearer.
+      username_claim: ""
     # Dynamic tools generated from ClickHouse views
     dynamic_tools: []
     #  - regexp: "db\\..*"

pkg/server/server_client.go

@@ -328,11 +328,11 @@ func (s *ClickHouseJWEServer) newClientWithOAuth(ctx context.Context, chCfg conf
 
 	// Bearer got an auth error — try Basic (ch-jwt-verify sidecar path).
 	log.Debug().Str("endpoint", endpoint).Msg("oauth: Bearer rejected by CH, probing Basic")
-	email, ok := emailFromUnverifiedJWT(token)
+	user, ok := basicUsernameFromJWT(token, cfg.UsernameClaim)
 	if !ok {
-		return nil, fmt.Errorf("oauth: bearer is not a JWT with an email claim")
+		return nil, basicUsernameError(cfg.UsernameClaim)
 	}
-	basicCfg := oauthApplyBasic(probeCfg, email, token)
+	basicCfg := oauthApplyBasic(probeCfg, user, token)
 	client, err := clickhouse.NewClient(ctx, basicCfg)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create ClickHouse client: %w", err)
@@ -351,11 +351,11 @@ func newClientForOAuthMethod(ctx context.Context, chCfg config.ClickHouseConfig,
 	case chOAuthMethodBearer:
 		chCfg = oauthApplyBearer(chCfg, token, oauthCfg)
 	case chOAuthMethodBasic:
-		email, ok := emailFromUnverifiedJWT(token)
+		user, ok := basicUsernameFromJWT(token, oauthCfg.UsernameClaim)
 		if !ok {
-			return nil, fmt.Errorf("oauth: bearer is not a JWT with an email claim")
+			return nil, basicUsernameError(oauthCfg.UsernameClaim)
 		}
-		chCfg = oauthApplyBasic(chCfg, email, token)
+		chCfg = oauthApplyBasic(chCfg, user, token)
 	}
 	client, err := clickhouse.NewClient(ctx, chCfg)
 	if err != nil {
@@ -446,6 +446,33 @@ func emailFromUnverifiedJWT(token string) (string, bool) {
 	return "", false
 }
 
+// basicUsernameFromJWT returns the ClickHouse Basic-auth username for token.
+// When usernameClaim is empty it keeps the default behavior (the `email` claim
+// with a namespaced `*/email` fallback). When set, it does a strict top-level
+// lookup of that single claim via oauth.UsernameFromExtra and fails closed
+// (ok=false) on a missing, empty, or non-string value — never falling back to
+// email or any other identity. The value is an unverified hint only; CH / the
+// ch-jwt-verify sidecar still validate the JWT.
+func basicUsernameFromJWT(token, usernameClaim string) (string, bool) {
+	if strings.TrimSpace(usernameClaim) == "" {
+		return emailFromUnverifiedJWT(token)
+	}
+	raw, ok := decodeUnverifiedJWTClaims(token)
+	if !ok {
+		return "", false
+	}
+	return oauth.UsernameFromExtra(raw, usernameClaim)
+}
+
+// basicUsernameError builds the fail-closed error returned when no usable Basic
+// username can be derived, naming the configured claim when one is set.
+func basicUsernameError(usernameClaim string) error {
+	if c := strings.TrimSpace(usernameClaim); c != "" {
+		return fmt.Errorf("oauth: bearer JWT has no usable Basic username (claim %q missing, empty, or non-string)", c)
+	}
+	return fmt.Errorf("oauth: bearer is not a JWT with an email claim")
+}
+
 // oauthExpiryClockSkewSecs tolerates small clock differences between this
 // server and the IdP that signed the token so a token expiring within seconds
 // does not bounce clients with slightly fast clocks.

pkg/server/server_client_test.go

@@ -221,6 +221,98 @@ func TestEmailFromUnverifiedJWT(t *testing.T) {
 	})
 }
 
+// TestBasicUsernameFromJWT covers the orchestration around the configurable
+// username_claim: unset preserves the email default (incl. namespaced
+// fallback); a set claim does a strict top-level lookup and fails closed on
+// missing/empty/non-string, never falling back to email.
+func TestBasicUsernameFromJWT(t *testing.T) {
+	t.Parallel()
+
+	t.Run("unset_claim_uses_email", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{"email": "alice@example.com"})
+		got, ok := basicUsernameFromJWT(tok, "")
+		require.True(t, ok)
+		require.Equal(t, "alice@example.com", got)
+	})
+
+	t.Run("unset_claim_whitespace_uses_email", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{"email": "alice@example.com"})
+		got, ok := basicUsernameFromJWT(tok, "   ")
+		require.True(t, ok)
+		require.Equal(t, "alice@example.com", got)
+	})
+
+	t.Run("unset_claim_namespaced_email_fallback", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{
+			"https://example.com/email": "alice@example.com",
+		})
+		got, ok := basicUsernameFromJWT(tok, "")
+		require.True(t, ok)
+		require.Equal(t, "alice@example.com", got)
+	})
+
+	t.Run("configured_username_claim", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{
+			"username": "alice",
+			"email":    "alice@example.com",
+		})
+		got, ok := basicUsernameFromJWT(tok, "username")
+		require.True(t, ok)
+		require.Equal(t, "alice", got)
+	})
+
+	t.Run("configured_claim_whitespace_trimmed", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{"preferred_username": "  bob  "})
+		got, ok := basicUsernameFromJWT(tok, "preferred_username")
+		require.True(t, ok)
+		require.Equal(t, "bob", got)
+	})
+
+	t.Run("configured_claim_missing_fails_closed", func(t *testing.T) {
+		t.Parallel()
+		// email present but the configured claim is absent — must NOT fall back.
+		tok := fakeJWT(t, map[string]interface{}{"email": "alice@example.com"})
+		_, ok := basicUsernameFromJWT(tok, "username")
+		require.False(t, ok)
+	})
+
+	t.Run("configured_claim_empty_fails_closed", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{"username": "   "})
+		_, ok := basicUsernameFromJWT(tok, "username")
+		require.False(t, ok)
+	})
+
+	t.Run("configured_claim_non_string_fails_closed", func(t *testing.T) {
+		t.Parallel()
+		tok := fakeJWT(t, map[string]interface{}{"username": 12345})
+		_, ok := basicUsernameFromJWT(tok, "username")
+		require.False(t, ok)
+	})
+
+	t.Run("configured_email_is_strict_top_level", func(t *testing.T) {
+		t.Parallel()
+		// With username_claim="email" set, the namespaced */email key is NOT
+		// consulted — explicit config means a strict single-claim lookup.
+		tok := fakeJWT(t, map[string]interface{}{
+			"https://example.com/email": "namespaced@example.com",
+		})
+		_, ok := basicUsernameFromJWT(tok, "email")
+		require.False(t, ok)
+	})
+
+	t.Run("configured_claim_not_a_jwt_fails_closed", func(t *testing.T) {
+		t.Parallel()
+		_, ok := basicUsernameFromJWT("only.two", "username")
+		require.False(t, ok)
+	})
+}
+
 // jwtWithClaims builds an unsigned-but-well-formed three-segment JWT string
 // (the signature segment is a dummy) for exp-claim tests. unverifiedExp never
 // checks the signature, so this is sufficient.