ORDS MCP derrière un reverse proxy#

L’audience

Audience = URL publique du MCP#

mcp.security.jwt.profile.audience est l’URL publique du MCP : la chaîne exacte que les clients envoient en OAuth resource=, et l’API identifier / aud JWT de l’IdP.

Même valeur aux quatre endroits :

Faire correspondre schéma, hôte, port, chemin. Pas de slash final, sauf si tous les côtés en ont un. https://my-proxy/mcp et https://my-proxy/ords/mcp sont des audiences différentes.

Pourquoi OpenCode impose l’exactitude#

Dans opencode.json, mcp.<name>.url est envoyée comme OAuth resource= à l’authorize :

https://<idp>/authorize
  ?…
  &resource=https://ords-mcp.company.com/mcp

Auth0/Entra fait correspondre resource= à l’API identifier ; cela devient le JWT aud ; ORDS vérifie aud contre mcp.security.jwt.profile.audience. Utiliser l’URL publique joignable depuis le poste, pas l’interne http://ords:8080/mcp.

Topologie recommandée

Hôte dédié, sans suppression de préfixe#

Donner un nom d’hôte à ORDS. Ne pas retirer /ords. Ne pas placer l’IdP sur cet hôte.

https://ords-mcp.company.com/mcp
  → http://ords:8080/mcp

https://ords-mcp.company.com/.well-known/oauth-protected-resource/mcp
  → http://ords:8080/.well-known/oauth-protected-resource/mcp

Proxyer ces deux chemins ORDS sans les réécrire. Audience : https://ords-mcp.company.com/mcp. C’est ce que supposent les docs Oracle MCP, ce lab et le Helm chart (ingress.hosts[].paths par défaut /). Un catch-all / convient uniquement parce que cet hôte est ORDS, pas l’IdP.

Transmettre : Host (ou X-Forwarded-Host), X-Forwarded-Proto: https, X-Forwarded-For. Désactiver le buffering et utiliser de longs timeouts sur /mcp (HTTP streamé).

ORDS doit toujours pouvoir sortir vers l’URL JWKS de l’IdP (NetworkPolicy, proxy, DNS). Ce trafic ne passe pas par ce reverse proxy.

Sketch nginx (hôte ORDS dédié)#

# ORDS MCP uniquement. IdP / JWKS restent sur login.company.com — ne pas les ajouter ici.
location /mcp {
    proxy_pass http://ords:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

# Métadonnées de *ressource* RFC 9728 sur l'hôte ORDS — pas JWKS, pas OIDC
location /.well-known/oauth-protected-resource/mcp {
    proxy_pass http://ords:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Récapitulatif

Les endpoints que le proxy doit atteindre#

Pas sur ce proxy#

Un GET/POST non authentifié sur /mcp doit renvoyer 401 avec un WWW-Authenticate pointant vers l’URL well-known ORDS ci-dessus. Ce document peut nommer l’IdP ; le client parle ensuite à l’IdP sur son propre hôte.