Post

The assistant deleted a document. Who did that? An audit log for an MCP server behind Keycloak

TL;DR: My Keycloak lab could say what an AI assistant is allowed to do. It couldn’t say what one did. I added an audit log to the MCP server: one JSON record per tool call, with the user, the client the assistant signed in through, the tool and how it ended. The API now logs which client each request came through, so it can tell alice in the web app from an assistant acting for alice. One request can be followed through Keycloak’s events, the MCP server’s log and the API’s log. Writing the records was the easy part. Deciding what a record must never contain took longer, and a review found three places where an action could happen with a wrong record or none.

The previous post put an MCP server in front of an API that Keycloak protects. An assistant signs in for a user, the user consents to scopes, and the server swaps each token for one the API accepts. The design has two layers: scopes say what the assistant may do, and the user’s roles say what the user may do.

A few days later I started writing a short post about it, and the first line I typed was a question: how do you know if your users used an AI agent to access your resources?

I couldn’t answer it. Everything in the lab was about the decision before a call. Nothing kept a record after it. The API was worse off than I’d realised: it received a valid token for alice, with alice’s roles, and logged nothing about where the request came from. If a document had gone missing, the honest answer to “was that alice, or an assistant acting for her?” would have been “one of the two”.

So this post is about the record. As before, it’s a lab: I’ve run it on my machine and in CI against a real Keycloak, and nowhere else.

One record

alice asks the assistant to delete a document. She consented to docvault:delete, and she isn’t an administrator. This is what the MCP server wrote, taken from the lab’s end-to-end check:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "time": "2026-11-17T19:49:46.147Z",
  "seq": 7,
  "event": "tool.call",
  "outcome": "refused",
  "trace.id": "a105d99b4cb9039f840307eac18fe6b0",
  "client.address": "::1",
  "user.id": "044bcbe0-893b-46bb-9605-d19c6dc9c1ea",
  "user.name": "alice",
  "client.id": "docvault-mcp-client",
  "scope": "openid docvault:delete docvault:write docvault:read email profile",
  "token.id": "onrtac:bd636f21-2ea4-b6c1-03b6-35367c141cc3",
  "session.id": "VLAsNyxapg6DEanU7THGNJs_",
  "tool": "delete_document",
  "reason": "api_forbidden",
  "document.id": "48b7cda7-9acb-4ca5-a2c1-b797788a4ad0"
}

It answers the questions I’d ask afterwards. Who: alice, by her Keycloak id and name. Through what: the client the assistant signed in through. With which permissions: the scopes on the token. What: the tool and the document. How it ended: refused, by the API.

The server writes each record as one line, to its normal log and, when a path is configured, to a JSON Lines file that only its owner can read.

There are four kinds of record:

EventWhenHow it can end
tool.calla tool ran, or refused inside the toolok, refused, rejected, not_found, error
scope.challengethe 403: the token lacks the tool’s scoperefused, with the scope that was needed
token.refusedthe 401: a token was presented and refusedrefused, or error
request.refuseda valid token, but a body the server won’t readrejected

The two layers stay apart

The previous post’s main point was that scopes and roles are two different questions. The log keeps them as two different records.

Earlier in the same run, alice’s assistant had only docvault:read and tried to create a document:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "time": "2026-11-17T19:49:46.021Z",
  "seq": 5,
  "event": "scope.challenge",
  "outcome": "refused",
  "user.name": "alice",
  "client.id": "docvault-mcp-client",
  "scope": "openid docvault:read email profile",
  "tool": "create_document",
  "reason": "missing_scope",
  "scope.required": "docvault:write"
}

(I’ve left out the id fields here; they’re the same ones as above.)

Read side by side, the two records say different things. scope.challenge means the assistant wasn’t allowed: the user hadn’t granted that permission. api_forbidden means the user wasn’t allowed: the scope was there and the role wasn’t. Someone reading the log a month later can tell an assistant reaching past its consent from a user reaching past their job.

What a record must not contain

A log that records “everything” becomes a second place to steal from. So the rules about what goes into a record live in one class, and the code that calls it can’t override them.

Identity comes only from a token the server has validated. A refused token is recorded like this:

1
2
3
4
5
6
7
8
9
{
  "time": "2026-11-17T19:49:45.538Z",
  "seq": 1,
  "event": "token.refused",
  "outcome": "refused",
  "trace.id": "e0f27231e560a6349a234d0c26247360",
  "client.address": "::1",
  "reason": "invalid_audience"
}

There’s no name in it, on purpose. The claims in a refused token are whatever the sender wrote. If the log copied them, anyone could put “carol” into my audit trail by sending a forged token with her name in it.

The reason is a fixed word. .NET’s validation errors can quote parts of the token they rejected. The log maps each kind of failure to a word from a short list, such as invalid_audience or expired, and never stores the message.

Never a token, never the client secret. A token is named by its id, the jti claim. That id can’t be used as a token, and it’s the same id Keycloak writes in its own event when it issues the token.

A rejected title is recorded by its length. The server refuses titles with control characters or invisible characters in them, because a title is text a model will read later. A title that was refused for what it might carry shouldn’t then be copied into a log. An accepted title is recorded.

client.id is the client, not the model. It says the assistant signed in through docvault-mcp-client. Nothing in a token says which model was behind it, and I didn’t want a field that implied otherwise.

Each of these has a test. To check that the tests were worth having, I broke the new code on purpose, one change at a time, twenty-two times. One break slipped through at first: recording a name from a token that hadn’t been validated. It has a test now.

Three logs, one request

Three systems each keep their own record, and no one of them has the whole picture.

flowchart LR
  K["Keycloak events<br/>sign-in, token issued,<br/>token exchanged"]
  M["MCP server audit log<br/>tool, outcome, user, client"]
  A["API access log<br/>request, status, user, client"]
  K -- "session id, token id" --- M
  M -- "trace id" --- A

Here is alice listing her documents, in all three.

Keycloak recorded the sign-in, the token it issued and the exchange (trimmed to the fields that matter):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{"type": "LOGIN", "clientId": "docvault-mcp-client",
 "sessionId": "FfZI7sv76-cVAsGiiEJR4cQk",
 "details": {"username": "alice", "consent": "persistent_consent"}}

{"type": "CODE_TO_TOKEN", "clientId": "docvault-mcp-client",
 "sessionId": "FfZI7sv76-cVAsGiiEJR4cQk",
 "details": {"token_id": "onrtac:244d2184-8f37-1bef-8ea6-c0c0452f6db5",
             "scope": "openid docvault:read email profile"}}

{"type": "TOKEN_EXCHANGE", "clientId": "http://localhost:5002/mcp",
 "sessionId": "FfZI7sv76-cVAsGiiEJR4cQk",
 "details": {"audience": "docvault-api",
             "subject_token_client_id": "docvault-mcp-client",
             "username": "alice"}}

The MCP server recorded the call, with the same session and token id:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "time": "2026-11-17T19:49:45.781Z",
  "seq": 2,
  "event": "tool.call",
  "outcome": "ok",
  "trace.id": "95282bec288420e2038900483b134f14",
  "user.name": "alice",
  "client.id": "docvault-mcp-client",
  "token.id": "onrtac:244d2184-8f37-1bef-8ea6-c0c0452f6db5",
  "session.id": "FfZI7sv76-cVAsGiiEJR4cQk",
  "tool": "list_documents"
}

The API recorded the request, with the same trace id:

1
access method=GET route=/documents/ status=200 user=alice sub=044bcbe0-893b-46bb-9605-d19c6dc9c1ea client=http://localhost:5002/mcp trace=95282bec288420e2038900483b134f14

The API’s line is new, and client= is the part that answers my question. After the exchange, the token the API receives is alice’s, with her roles. Its azp claim, the party the token was issued to, is the MCP server’s client. The same request from the React app carries azp=docvault-web-react. The API had always received that claim and never written it down.

Two details cost me some time:

  • Keycloak didn’t keep the exchange. The realm saves a chosen list of event types, and TOKEN_EXCHANGE wasn’t on it. My first draft of the documentation said Keycloak’s events show the exchange. They didn’t, until I added the type and checked through the admin API.
  • Successful events aren’t in Keycloak’s server log. By default they go to its database, and only failures are logged. If you look for a LOGIN in the container’s output, you won’t find one. The admin console has them under the realm’s events.

The lab’s end-to-end check now signs in, makes its calls, and then reads all three logs. It checks that each call is on record under the right user, that no record holds a token, that Keycloak’s events carry the same token id and session, and that the API logged alice’s call under the same trace id.

What a review found

As with the server itself, I asked a second, independent Claude session to review the change. It found one problem I’d call serious and several smaller ones. All of them fit the theme of this series: nothing failed, and the record was wrong or missing.

A caller who hung up got the action without the record

The tool wrote its record after the API answered. If the client closed the connection while the API was still working, .NET cancelled the call, and my code treated a cancelled call as nothing to record. But the API may already have acted. Hanging up is something a client can do on purpose, so this was a way to delete a document and leave no trace in the MCP server’s log.

The call is now recorded with what was asked, as error with the reason cancelled. A test now abandons a call while the API is still working and expects the record. The reviewer checked the fix a second way, by closing a real connection mid-call.

The trace id was the caller’s

ASP.NET Core adopts an incoming traceparent header by default. That’s what you want between your own services. On a server that outsiders call, it meant a caller could choose the trace id in my audit records, and give a hundred calls the same one.

The MCP server now ignores an incoming trace header and starts its own trace for each request. It still passes its own id on to the API, which is what joins the two logs.

A fault that read as an attack

If the server couldn’t fetch Keycloak’s signing keys, every token failed validation, and the log said invalid_signature. That reads like someone sending forged tokens, when really my server couldn’t reach Keycloak.

So refused is now kept for decisions, and faults are an error: signing_keys_unavailable, exchange_failed when Keycloak doesn’t answer the exchange, and so on. The difference matters to whoever gets paged.

GitHub’s code scanning added one of its own: the API’s new log line wrote the request’s method as it arrived. It now writes one of a fixed set of names.

What this isn’t

  • A production audit log. It’s a local file and a log line, and nothing ships it anywhere. If a write to the file fails, the server says so in its log and carries on. Records aren’t signed or chained, so whoever can write the file can change it.
  • A record of every request. A request with no token isn’t recorded: that’s how every MCP client starts. Nor is a call the SDK answers before a tool runs, such as an unknown tool name. Neither reaches the API.
  • A record of what the model was asked. The log knows the tool call. It doesn’t know the prompt behind it, or which model made it.
  • OpenTelemetry. The trace id is in every record, so an exporter could be added. I haven’t.

What I took away

  • Log the client as well as the user. The exchanged token said all along who was acting for alice. It took one log line to keep it.
  • Decide what a record may hold in one place. Especially what it may never hold: a token, a refused token’s claims, text you refused for a reason.
  • Record the attempt, not only the result. An action whose record depends on the caller staying connected can be done without one.
  • Keep refusals and faults apart. One is a decision and the other is an outage.
  • Check your own documentation against the running system. Mine claimed an event Keycloak wasn’t keeping.

Try it

v1.1.0 of the lab is the version this post describes. It needs Docker, .NET 10 and Terraform:

1
2
3
4
5
git clone https://github.com/MagnusJohansson/keycloak-poc
cd keycloak-poc
make up && make seed && make api     # Keycloak, the realm, the API
make mcp                             # the MCP server on :5002
make assert-mcp                      # 34 checks against the real stack

Then read what it left behind:

1
2
jq -c '[.seq, .event, .outcome, ."user.name", .tool, .reason]' .lab/mcp-audit.jsonl
grep 'access method' .lab/api.log

The details are in the lab’s write-up.

Earlier in this series: An MCP server behind Keycloak: what may the assistant do, and for whom? and Sign-in works. Every API call returns 401.


I wrote this post with Claude’s help, the same way I built the audit log. A second, independent Claude session reviewed the change over two rounds. The decisions and the final check of every claim are mine.

This post is licensed under CC BY 4.0 by the author.