Securing remote servers with OAuth

PKCE, concretely

PKCE (proof key for code exchange, said "pixy") stops a stolen authorization code from being used. Picture tearing a raffle ticket in two: you hand in one half now, and only the person holding the other half can collect the prize. Before step 4, the client makes a random secret, the code verifier: 43 to 128 characters of letters, digits and -._~. It sends only its hash, the code challenge, in step 4:

import base64, hashlib, secrets

def challenge(verifier):
    digest = hashlib.sha256(verifier.encode("ascii")).digest()
    return base64.urlsafe_b64encode(digest).decode().rstrip("=")

# The worked example from the PKCE standard, RFC 7636:
print(challenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"))

verifier = secrets.token_urlsafe(32)          # 43 characters from the allowed set
print(len(verifier), challenge(verifier))

The first line should print E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM, the published answer. In step 6 the client sends the verifier itself, and the authorization server checks that its hash matches the challenge. Someone who intercepted the code in step 5 never saw the verifier, so the code is useless to them. MCP requires the S256 method shown here.

import hashlib, base64
verifier = "abc"
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=")
print(challenge == verifier)

The resource parameter: tokens for one server

A key card coded for one hotel won't open a room in another, even if both belong to the same chain. The client must send resource=https://shop.example/mcp (the server's canonical URI) in both the authorization and token requests. The authorization server then puts that server in the token's audience (the aud claim). A token for the shop's MCP server won't work at the calendar's MCP server, even if both trust the same authorization server.

Checking tokens on the server

On every request, the MCP server validates the token, as you did with JWTs in Phase 8. A door guard asks the same four things about a pass: is it real, is it in date, is it for this building, and does it open this floor?

• It must be genuine (a valid signature, or confirmed by asking the authorization server).
• It must not be expired.
• Its audience must be this server. The spec is firm: servers must accept only tokens issued for them.
• It must carry the scopes the operation needs.

Failures have specific answers:

The 403 lists the scopes needed, so the client can ask the user to approve more and retry. That's called step-up authorization.

THIS_SERVER = "https://shop.example/mcp"

def check_token(token, needed_scope, now):
    if not token.get("signature_ok"):
        return 401, "invalid token"
    if token["exp"] <= now:
        return 401, "expired"
    if token["aud"] != THIS_SERVER:
        return 401, "wrong audience"
    if needed_scope not in token["scope"].split():
        return 403, f"needs scope {needed_scope}"
    return 200, "ok"

good = {"signature_ok": True, "exp": 2000, "aud": THIS_SERVER, "scope": "orders:read"}
print(check_token(good, "orders:read", now=1000))
print(check_token(good, "orders:write", now=1000))
print(check_token(good, "orders:read", now=3000))
print(check_token({**good, "aud": "https://other.example/mcp"}, "orders:read", now=1000))

No token passthrough

Your MCP server may call other APIs for the user, such as the shop's order system. It's tempting to forward the token the client sent. Don't. The spec forbids it, for two reasons.

Your server would then accept tokens meant for someone else, which skips the audience check. And downstream systems would see a request that seems to come straight from the client, with your server's checks bypassed. That's a confused deputy: a trusted helper tricked into using its authority for someone else.

Your server should get its own token for the downstream API, through a separate grant, and keep each token to the audience it was issued for.

In plain words: a token opens one door. If your server needs another door, it gets its own token for it.

No passthrough

A server must never forward the client's token to another API. Get its own token for that, so that a token only ever works where it was meant to.