OIDC
rta mcp serve --http refuses to start without a way to verify who is calling. There are two, and they answer different questions. A static token from --token-file names whoever holds the string. An OIDC issuer names a person your identity provider already knows, which is what makes "one instance per person, authenticating as that person" mean anything — the record then carries a subject your IdP can resolve back to a human, not a label somebody chose.
This page is what rta actually verifies, how an MCP client finds where to log in, a Keycloak walkthrough because it is the provider with the sharpest edge, and the failure messages, which go somewhere you might not look.
The four flags
rta mcp serve --http 0.0.0.0:8080 \
--oidc-issuer https://id.example.com/realms/main \
--oidc-audience https://rta.example.com \
--oidc-subject 8f14e45f-ceea-467a-9c1a-2d7c4f0b1a33 \
--oidc-resource https://rta.example.comAll four are required together, and the three refusals say why:
an --oidc-issuer needs --oidc-audience— without it, a token minted for any other service by the same issuer authenticates here.an --oidc-issuer needs at least one --oidc-subject — an issuer and audience alone identify an application, not a person— without it, every identity that issuer will ever mint is accepted, which is the whole namespace of your IdP rather than one person.an --oidc-issuer needs --oidc-resource— without it, an OAuth client meets a refusal that never says where to log in, and the server is one nobody can use with no sign of why.
--oidc-subject is repeatable and comma-splitting. --oidc-resource is the URL MCP clients are configured with, the one the proxy in front serves, never the address rta binds: rta cannot learn it from anything it sees, since a Host header is whatever a relay wrote. It has to be https://, or http:// on a loopback address, with no query, fragment or user name, and a path, if it has one, of letters, digits and - . _ ~. The audience is the same URL here, which is the recommendation below rather than a default.
How an MCP client finds the issuer
An OAuth client — Claude Code, VS Code, anything built on an MCP SDK — is configured with one URL and has to find the identity provider from there. Its first request carries no token, and rta answers it with the refusal every such request gets, plus a header saying where to look:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://rta.example.com/.well-known/oauth-protected-resource"That URL answers without a token, with the RFC 9728 protected resource metadata — three fields, and nothing else:
{"resource":"https://rta.example.com","authorization_servers":["https://id.example.com/realms/main"],"bearer_methods_supported":["header"]}The client reads the issuer there, discovers its endpoints, logs in at it in a browser asking for a token for resource, and comes back with one. rta takes no part in the login: it says where the login happens, and verifies what arrives afterwards the way the next section describes.
- Configure the client with exactly the URL rta prints. The startup banner says
rta: configure MCP clients with exactly https://rta.example.com — …. A client comparesresourcewith the URL it was given byte for byte, sohttps://rta.example.com/, with the slash, or another path, is refused by the client before it logs in at all. rta writes the URL it is given with the host lowercased and trailing slashes removed. - A URL with a path is described at a path of its own. With
--oidc-resource https://rta.example.com/mcpthe document is at/.well-known/oauth-protected-resource/mcp, as RFC 9728 places it, and the root form is not served, because it would describe the bare host, which is another resource. - The proxy has to pass
/.well-known/oauth-protected-resourceto rta unchanged. An ingress that routes only a path prefix to rta never forwards it, and the client concludes there is nothing to find. The chart's default ingress path,/, forwards everything.
The document is public on purpose — a client reads it before it holds anything — so it tells anyone who asks which issuer this server trusts. It never names a subject or the audience, and it lists no scope, because rta authorizes with grants rather than OAuth scopes. A server with static tokens alone publishes nothing and its 401 carries no header: there is no issuer to name, and a document without one would start a login that cannot finish.
The client also needs a client of its own at the identity provider: registered there by hand, as a public client allowing the loopback redirect addresses it listens on, or through whatever dynamic registration the provider allows. That is between the client and the provider.
What rta checks, exactly
The bearer is a signed JWT, verified offline. rta checks the token itself against the keys the issuer publishes, and never asks the issuer about it: there is no RFC 7662 introspection, which would put a client secret on this server and a round trip to the identity provider in front of every call. An opaque access token, or an encrypted one, is therefore refused. Keycloak's access tokens are signed JWTs unless the realm is told otherwise; with any other provider, decode one before relying on it. printf %s "$TOKEN" | rta codec jwt shows which kind you hold: a signed token decodes to its header and claims, an encrypted one to a header naming the key it is sealed for. Beyond the claims in the table below nothing is read — not the header's typ, not azp, not scope.
Discovery happens once, at startup. rta fetches <issuer>/.well-known/openid-configuration before accepting anything, with a 15-second timeout, and refuses to start if the issuer is unreachable. That is deliberate: a server that starts and then rejects every call looks healthy to an orchestrator and is not. The listener is bound before discovery, so a port clash reports first.
The discovered document's own issuer field must equal what you passed. A trailing slash difference is a mismatch.
The issuer must be https://, or http:// for a loopback address only — discovery and the key set are fetched from wherever it points, so plain http anywhere else is refused: --oidc-issuer %q must be https — plain http is only accepted for a loopback address.
Signing keys are fetched lazily and re-fetched on an unknown kid. There is no polling interval; the first fetch happens on the first token. A key rotation is picked up on the first token signed by the new key, so rotation needs no restart.
Accepted algorithms are your provider's advertised id_token_signing_alg_values_supported intersected with RS256/384/512, ES256/384/512, PS256/384/512 and EdDSA. none and HMAC algorithms are not in that set, and the token's own alg header never widens it.
Claims:
| Claim | Checked how |
|---|---|
iss | Exact string equality with the configured issuer. No leeway. |
aud | Exact, case-sensitive membership of --oidc-audience. A string aud and a single-element array behave identically. |
sub | Exact, case-sensitive match against one of the --oidc-subject values. |
exp | Required, and zero leeway — no clock skew is forgiven here. |
nbf | Checked only when present, with five minutes of leeway. |
iat | Parsed and not validated. |
azp | Never consulted. See below. |
azp is not aud, and this is the one that catches people. Keycloak puts the requesting client's id in azp and, by default, does not add it to aud at all. rta reads aud and nothing else, so a Keycloak token that looks correct in a JWT decoder is rejected until the client is given an audience mapper. That is the next section.
Only sub is matched. Not email, not preferred_username, not groups. If your IdP's sub is an opaque UUID — Keycloak's is — then that UUID is what goes in --oidc-subject.
Make the audience the resource URL
--oidc-audience is whatever string the issuer puts in aud, and a client id such as rta works. The resource URL works better: pass the --oidc-resource value as --oidc-audience too, and have the identity provider put that URL in aud. A token is then good for this one instance, not for every rta the same realm issues tokens to. rta does not default one to the other, because the provider has to be told as well, and a default it was never told about would reject every token.
Keycloak ignores the resource parameter a client sends unless its experimental resource indicators feature is on, so there an audience mapper is what puts the URL in aud (step 2 below). A provider that does mint aud from resource takes it as the client sent it, and a client built on browser URL parsing sends a bare host as https://rta.example.com/, with a slash an exact match refuses: give the server a URL with a path, or set --oidc-audience to what the tokens actually carry.
Keycloak
Keycloak is the worked example because two of its defaults are wrong for this, both quietly.
1. The issuer is realm-scoped. It is https://keycloak.example.com/realms/<realm>, not the host. Getting this wrong produces oidc: id token issued by a different provider.
2. The audience needs a mapper. Create a client — call it rta — then add a mapper that puts this server's URL into aud:
Clients → rta → Client scopes → rta-dedicated → Add mapper → By configuration → Audience
- Name:
rta-audience - Included Custom Audience:
https://rta.example.com, the--oidc-resourcevalue exactly - Add to access token: On
and pass the same URL as --oidc-audience. Without it the token carries "azp": "rta" and an aud of account, and rta rejects it with oidc: expected audience "https://rta.example.com" got ["account"]. Nothing in the Keycloak UI suggests this is missing. Naming the client instead — Included Client Audience rta, with --oidc-audience rta — works too, and accepts a token minted for any rta the realm serves.
A mapper on rta-dedicated reaches the tokens issued to the rta client and no others. An MCP client that registers a client of its own rather than logging in as rta gets its tokens under that client, so for it the mapper goes on a client scope that client is given.
3. Find the subject. Keycloak's sub is the user's internal UUID, visible in Users → the user → Details → ID, or by decoding a token you hold in $TOKEN (step 4 fetches one and decodes it in the same line):
printf %s "$TOKEN" | rta codec jwtThat is the value for --oidc-subject. It is stable across username and email changes, which is the reason to prefer it, and opaque, which is the reason to write a comment next to it in your values file.
4. Check the whole thing before deploying anything:
read -rs PASSWORD
printf %s "$PASSWORD" | curl -s -X POST \
https://keycloak.example.com/realms/main/protocol/openid-connect/token \
-d grant_type=password -d client_id=rta \
-d username=you --data-urlencode password@- | jq -r .access_token | rta codec jwtPiped rather than passed as an argument, the token never appears in the process list, where every user on the machine can read an argument for as long as the command runs. The password is kept out of it the same way: read -s takes it without echoing it, and printf, a shell builtin, hands it to curl on standard input, where password@- reads it. A copied Authorization: Bearer … line decodes as it is, and so does a token the realm encrypts: its header says which key it is sealed for.
To check the signature too, hand it the realm's key set. rta does not fetch it for you — a decoder that followed a URL it was given would be a network call nobody granted — so fetch it yourself:
… | jq -r .access_token | rta codec jwt \
--key "$(curl -s https://keycloak.example.com/realms/main/protocol/openid-connect/certs)"The verification section, printed after the header and the claims, then leads with VERIFIED and the kid that matched, or the command fails naming why: no key with the token's kid (the realm rotated its keys), a key of the wrong type, a token changed after it was signed. rta codec jwk on the same key set lists every kid, and flags a key the realm should not be publishing.
Read three fields off that output: iss must equal --oidc-issuer exactly, aud must contain --oidc-audience, and sub must be a value you passed to --oidc-subject. If all three match and the call is still refused, the reason is in the server's stderr — see below.
Any other provider
Nothing above is Keycloak-specific except the mapper. For a generic provider:
- Issuer: whatever
.well-known/openid-configurationlives under. Auth0 useshttps://<tenant>.auth0.com/, and the trailing slash is part of it. Okta useshttps://<org>.okta.com/oauth2/<server>. Google useshttps://accounts.google.com. - Audience: the API identifier or client id your provider puts in
aud. Providers that distinguish an "API" from a "client" (Auth0, Okta) want the API identifier, and the token request usually has to ask for it explicitly. Both take a URL as an API identifier, so it can be the--oidc-resourcevalue. - Subject: whatever that provider puts in
sub. Google's is a numeric string; Auth0's looks likeauth0|65f….
Decode a real token before writing the flags. Every field rta checks is visible in it.
Both mechanisms at once
--token-file and --oidc-issuer can be set together, and a bearer token that the static verifier rejects falls through to the OIDC one. That is useful — an OIDC instance can still hold one static token for a Prometheus scraper, which cannot perform an OIDC exchange on a scrape interval.
It is worth being clear about what it costs. Two verifiers on one endpoint means the endpoint's strength is the weaker of the two, and a static token in a file is weaker than an identity your IdP can revoke. Use it for the machine that has no other option, keep that token's label distinct so the record says which one called, and do not let it become the way people log in.
When it does not work
The client is told nothing. Every verification failure returns the same generic invalid-token response — a caller cannot learn whether the audience was wrong or the subject was unknown, because that difference is a probing oracle. The reason goes to the server's stderr:
rta: mcp http: oidc token rejected: oidc: expected audience "https://rta.example.com" got ["account"]
rta: mcp http: oidc token subject "9c1a…" is not in the allowed list
rta: mcp http: bearer token rejected by every configured verifier: …In Kubernetes that is kubectl logs. If you are looking at a 401 and the logs say nothing at all, the request never reached the verifier — check that you sent Authorization: Bearer … and that you are talking to the MCP port rather than the observation one.
| Message | Cause |
|---|---|
oidc: expected audience "X" got ["Y"] | No audience mapper, or the wrong --oidc-audience. |
oidc: id token issued by a different provider, expected "X" got "Y" | Issuer mismatch — usually a missing realm path or a trailing slash. |
oidc: token is expired | Zero leeway on exp; also check the pod's clock. |
failed to verify signature | Token signed by a key the issuer does not advertise. |
subject "…" is not in the allowed list | sub is not one of the --oidc-subject values. Decode the token. |
reaching the --oidc-issuer at startup | Discovery failed. The server did not start. |
an --oidc-issuer needs --oidc-resource at startup | The URL clients are configured with was not given. |
--oidc-resource "…" must be https, or has a query or a fragment, at startup | The URL is not one a client can be given: plain http off loopback, or a ? or # anywhere in it. |
| The client says the resource does not match, or tries to log in at rta itself | The URL the client was given differs from --oidc-resource (a trailing slash, another path), or the proxy does not pass /.well-known/oauth-protected-resource to rta. Nothing reaches the server's stderr: the client stops before it sends a token. |
Repeated failures are slowed down. After five refusals in a minute from one address, responses are delayed 250ms, doubling to two seconds. A misconfigured client retrying in a loop will look slow before it looks broken.
What lands in the record
Two names, and they are not the same thing.
Agent is the --as name — the identity grants are issued to and policy is written against. Credential is the OIDC sub, recorded beside it, bounded to 64 bytes with a hash suffix if longer.
So the record answers both "which agent was this" and "which human's token authenticated it", and rta lock add can target either. This is why an instance per person is worth the trouble: with a shared server both columns collapse to the same uninformative value.
In Kubernetes
charts/rta takes the same values per instance, and derives the fourth:
servers:
tobi:
host: rta-tobi.example.com # auth.oidc.resource defaults to https://<host>
auth:
oidc:
enabled: true
issuer: https://keycloak.example.com/realms/main
audience: https://rta-tobi.example.com
subjects:
- 8f14e45f-ceea-467a-9c1a-2d7c4f0b1a33 # Keycloak user ID for tobiauth.oidc.resource defaults to https://<host>, the host the ingress serves, the way the operator URL does; set it when clients reach the instance under a path. The chart refuses to render an issuer with no audience or no subject, or one with neither host nor resource, so those startup refusals arrive at helm install time instead of as a CrashLoopBackOff.
One deployment note that follows from discovery happening at startup: if your IdP and rta start together, rta can lose the race and refuse to start. It restarts, and a startupProbe with room to retry covers it — but a NetworkPolicy that never lets the pod reach the IdP produces the same symptom permanently, so check egress before blaming the ordering.
Next
Kubernetes — the same idea as a chart: one instance per person, the decisions to make before setting a value, and day two.
