This is an automated email from the ASF dual-hosted git repository.
jerryshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new d262d5023c [#14652] fix(mcp-server): Fingerprint credentials in audit
principals (#14601)
d262d5023c is described below
commit d262d5023c1fd3942a3674864698189da371b5a3
Author: Santosh Kumar Puppala <[email protected]>
AuthorDate: Thu Nov 5 05:47:09 2026 -0500
[#14652] fix(mcp-server): Fingerprint credentials in audit principals
(#14601)
### What changes were proposed in this pull request?
For Bearer and other non-Basic schemes, the audit principal is now the
first 16 hex characters of the SHA-256 of the whole credential. Before
it was the first 8 characters of the credential. JWT claims are not
read, and Basic is unchanged. The docs row for `principal` is updated.
### Why are the changes needed?
The first 8 characters of a JWT come from its header, so callers whose
tokens share a header all got the same principal. Tokens of 8 characters
or less were also logged in full.
Fixes #14652
Found in #11571.
### Does this PR introduce _any_ user-facing change?
Yes, the `principal` value in the audit log has a new format. A
refreshed token gets a new value.
The OAuth service identity goes through the same function as a caller's
header, so it is hashed too. `oauth:mcp-serv` becomes
`oauth:0d315e3c73d7840c`. The client ID is still in the startup log.
The hash has no key, so the same token keeps the same value across
restarts and replicas. Let me know if you would prefer a keyed hash with
a configured secret.
### How was this patch tested?
`uv run pytest tests/unit/` gives 316 passed. The new tests cover JWTs
for different users with the same header, the same claims with a
different signature, the audit record from the middleware, and a token
that is not valid UTF-8.
---
docs/gravitino-mcp-server.md | 4 +-
mcp-server/mcp_server/core/audit.py | 10 +++--
mcp-server/tests/unit/test_audit.py | 87 +++++++++++++++++++++++++++++++++----
3 files changed, 87 insertions(+), 14 deletions(-)
diff --git a/docs/gravitino-mcp-server.md b/docs/gravitino-mcp-server.md
index 81087397e9..f466fe9612 100644
--- a/docs/gravitino-mcp-server.md
+++ b/docs/gravitino-mcp-server.md
@@ -364,11 +364,13 @@ Every tool invocation is recorded as one structured JSON
line in `gravitino-mcp-
| Field | Description
|
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timestamp` | UTC ISO-8601 time of the call.
|
-| `principal` | Caller identity: username for `Basic` simple auth,
`bearer:<first-8-chars>` for a Bearer token,
`oauth:<first-8-chars-of-client-id>` when OAuth client-credentials is the
service identity (stdio or HTTP with no caller header), or `anonymous` when no
identity is present. |
+| `principal` | Caller identity: username for `Basic` simple auth,
`bearer:<first-16-hex-of-sha256-of-token>` for a Bearer token (a fingerprint of
the token, so it changes when the token is refreshed),
`oauth:<first-16-hex-of-sha256-of-client-id>` when OAuth client-credentials is
the service identity (stdio or HTTP with no caller header), or `anonymous` when
no identity is present. |
| `tool` | Name of the invoked MCP tool.
|
| `outcome` | `allow` for successful calls, `deny` for failed ones. `deny`
is emitted for any tool-call exception (authorization denial being the common
case); inspect `error_type` to disambiguate. |
| `error_type` | Exception class name, present only when `outcome` is `deny`.
|
+For every scheme other than `Basic`, `principal` is a fingerprint of one
credential, not a stable user identity. The hash has no key, so the fingerprint
suits high-entropy tokens only: a short static credential can be recovered from
the log by guessing. To trace what one user did, use the Gravitino server's
[audit log](./gravitino-server-config.md#audit-logging).
+
Example record:
```json
diff --git a/mcp-server/mcp_server/core/audit.py
b/mcp-server/mcp_server/core/audit.py
index a8d7d6224e..e5d06155f4 100644
--- a/mcp-server/mcp_server/core/audit.py
+++ b/mcp-server/mcp_server/core/audit.py
@@ -17,6 +17,7 @@
import base64
import binascii
+import hashlib
import json
import logging
from datetime import datetime, timezone
@@ -28,8 +29,8 @@ def _extract_principal(authorization: str) -> str:
"""Derive a display principal from a raw Authorization header value.
- "Basic <base64(user:secret)>" → "<user>" (Gravitino simple auth)
- - "Bearer <token>" → "bearer:<first-8-chars-of-token>"
- - "<scheme> <credential>" → "<scheme>:<first-8-chars-of-credential>"
+ - "Bearer <token>" → "bearer:<sha256(token)[:16]>"
+ - "<scheme> <credential>" → "<scheme>:<sha256(credential)[:16]>"
- empty / missing / unparsable → "anonymous"
The credential may itself contain spaces (a custom scheme is free to use a
@@ -54,7 +55,8 @@ def _extract_principal(authorization: str) -> str:
return "anonymous"
user = decoded.split(":", 1)[0]
return user if user else "anonymous"
- return f"{scheme}:{credential[:8]}"
+ digest = hashlib.sha256(credential.encode("utf-8", "surrogatepass"))
+ return f"{scheme}:{digest.hexdigest()[:16]}"
def emit(
@@ -68,7 +70,7 @@ def emit(
"""Write one structured JSON audit record to the audit logger.
Args:
- principal: Identity derived from the request (e.g. "bearer:abc12345"
or "anonymous").
+ principal: Identity derived from the request (e.g.
"bearer:f39dac6cbaba535e" or "anonymous").
tool: MCP tool name that was invoked.
outcome: "allow" for successful calls, "deny" for failed calls. Note
the
AuditMiddleware emits "deny" for any tool-call exception (an
diff --git a/mcp-server/tests/unit/test_audit.py
b/mcp-server/tests/unit/test_audit.py
index 6071878a84..23ba80b732 100644
--- a/mcp-server/tests/unit/test_audit.py
+++ b/mcp-server/tests/unit/test_audit.py
@@ -16,9 +16,12 @@
# under the License.
import asyncio
+import base64
+import hashlib
import json
import logging
import unittest
+from unittest.mock import patch
from fastmcp import Client
@@ -96,10 +99,10 @@ class TestAuditEmit(unittest.TestCase):
class TestExtractPrincipal(unittest.TestCase):
"""Unit tests for audit._extract_principal()."""
- def test_bearer_token_truncated_to_8_chars(self):
+ def test_bearer_token_is_fingerprinted(self):
self.assertEqual(
audit._extract_principal("Bearer abcdefghijklmnop"),
- "bearer:abcdefgh",
+ "bearer:f39dac6cbaba535e",
)
def test_empty_header_returns_anonymous(self):
@@ -108,8 +111,41 @@ class TestExtractPrincipal(unittest.TestCase):
def test_none_like_empty_returns_anonymous(self):
self.assertEqual(audit._extract_principal(None), "anonymous")
- def test_short_token_uses_full_token(self):
- self.assertEqual(audit._extract_principal("Bearer abc"), "bearer:abc")
+ def test_short_token_is_fingerprinted(self):
+ self.assertEqual(
+ audit._extract_principal("Bearer abc"),
+ "bearer:ba7816bf8f01cfea",
+ )
+
+ def test_jwts_sharing_a_header_get_distinct_principals(self):
+ tokens = [_jwt_for(subject) for subject in ("alice", "bob", "carol")]
+ self.assertEqual(len({token.split(".")[0] for token in tokens}), 1)
+ principals = {
+ audit._extract_principal(f"Bearer {token}") for token in tokens
+ }
+ self.assertEqual(len(principals), 3)
+
+ def test_same_claims_under_another_signature_get_another_principal(self):
+ self.assertNotEqual(
+ audit._extract_principal(f"Bearer {_jwt_for('alice')}"),
+ audit._extract_principal(f"Bearer {_jwt_for('alice', b'forged')}"),
+ )
+
+ def test_jwt_principal_is_the_fingerprint_of_the_whole_token(self):
+ token = _jwt_for("alice")
+ self.assertEqual(
+ hashlib.sha256(token.encode()).hexdigest()[:16], "3056aa588a7ade5e"
+ )
+ self.assertEqual(
+ audit._extract_principal(f"Bearer {token}"),
+ "bearer:3056aa588a7ade5e",
+ )
+
+ def test_credential_that_is_not_valid_utf8_still_yields_a_principal(self):
+ self.assertEqual(
+ audit._extract_principal("Bearer \udcff\udcfe"),
+ "bearer:8db8cb0aa243f9fc",
+ )
def test_basic_auth_decodes_user(self):
"""Simple auth header 'Basic base64(alice:dummy)' -> principal
'alice'."""
@@ -124,16 +160,17 @@ class TestExtractPrincipal(unittest.TestCase):
)
def test_other_scheme_falls_back_to_scheme_prefix(self):
- """A non-Basic scheme stays attributable via '<scheme>:<first-8>'."""
+ """A non-Basic scheme stays attributable via
'<scheme>:<sha256[:16]>'."""
self.assertEqual(
- audit._extract_principal("Negotiate abc123"), "negotiate:abc123"
+ audit._extract_principal("Negotiate abc123"),
+ "negotiate:6ca13d52ca70c883",
)
def test_custom_scheme_with_multi_word_credential(self):
"""A credential containing spaces is not treated as unparsable."""
self.assertEqual(
audit._extract_principal("Custom-Scheme key=abcdefghij, sig=xy"),
- "custom-scheme:key=abcd",
+ "custom-scheme:356588a47129863a",
)
def test_extra_space_between_scheme_and_credential(self):
@@ -232,7 +269,28 @@ class TestAuditMiddlewareIntegration(unittest.TestCase):
asyncio.run(_run())
record = json.loads(self.log_records[0])
- self.assertEqual(record["principal"], "bearer:abcdef12")
+ self.assertEqual(record["principal"], "bearer:da4ec3358a10c9b0")
+
+ def test_two_jwt_callers_get_separate_records_without_credentials(self):
+ tokens = [_jwt_for("alice"), _jwt_for("bob")]
+
+ async def _run():
+ async with Client(self.mcp) as client:
+ await client.call_tool("get_list_of_catalogs")
+
+ for token in tokens:
+ with patch(
+ "mcp_server.server._get_request_authorization",
+ return_value=f"Bearer {token}",
+ ):
+ asyncio.run(_run())
+
+ records = [json.loads(line) for line in self.log_records]
+ self.assertNotEqual(records[0]["principal"], records[1]["principal"])
+ forbidden = {"alice", "bob", *".".join(tokens).split(".")}
+ for line in self.log_records:
+ for material in forbidden:
+ self.assertNotIn(material, line)
def test_principal_falls_back_to_oauth_client_id(self):
"""With no request header, OAuth client-credentials is attributable."""
@@ -253,7 +311,7 @@ class TestAuditMiddlewareIntegration(unittest.TestCase):
asyncio.run(_run())
record = json.loads(self.log_records[0])
- self.assertEqual(record["principal"], "oauth:mcp-serv")
+ self.assertEqual(record["principal"], "oauth:0d315e3c73d7840c")
def test_failed_tool_call_emits_deny_record(self):
"""A tool call that raises an exception produces an audit record with
outcome=deny."""
@@ -301,3 +359,14 @@ class _CapturingHandler(logging.Handler):
class _FailingCatalogOperation:
async def get_list_of_catalogs(self) -> str:
raise GravitinoException("Error code: 1003, Error type: FORBIDDEN")
+
+
+def _jwt_for(subject: str, signature: bytes = b"signature") -> str:
+ parts = (
+ json.dumps({"alg": "RS256", "typ": "JWT"}).encode(),
+ json.dumps({"sub": subject}).encode(),
+ signature,
+ )
+ return ".".join(
+ base64.urlsafe_b64encode(part).decode().rstrip("=") for part in parts
+ )