OAuth 2.0 + PKCE, expliqué comme si on ne l’avait jamais vu

Le casting

Les 4 acteurs (les connaître = comprendre OAuth)

Dans toute discussion OAuth, se demander « qui joue quel rôle ? » répond à 80 % des questions. Les noms anglais entre parenthèses sont ceux des specs — ils reviennent partout.

Le film, pas à pas

La séquence OAuth 2.0 + PKCE en 10 étapes

C’est ce qui se passe quand on lance opencode mcp auth ords-mcp. Deux types d’échanges alternent : des redirections navigateur (l’utilisateur voit Auth0) et des échanges serveur→serveur en arrière-plan (OpenCode parle directement à Auth0 puis à ORDS).

1. OpenCode (client)

   Prépare l’URL d’autorisation et ouvre le navigateur. Elle contient : l’identité du client (client_id), où renvoyer l’utilisateur (redirect_uri sur le port local 19876), ce qu’on demande (scope = permission MCP + offline_access), et surtout resource=http://127.0.0.1:8080/mcp qui dit « je veux un jeton pour cette API précise ». OpenCode génère aussi un code_challenge (le « C » de PKCE).

2. Navigateur (via l’utilisateur) → Auth0

   L’utilisateur se connecte chez Auth0 (Google ou compte local). Auth0 vérifie le mot de passe / la session.

3. Auth0 (serveur d’autorisation)

   Une Action post-login s’exécute : elle copie les rôles de l’utilisateur (POOL.HR, POOL.FIN…) dans une claim nommée roles2. Pourquoi pas roles ? Auth0 réserve ce nom et n’y mettra jamais une liste personnalisée.

4. Auth0 → navigateur

   Auth0 redirige le navigateur vers http://127.0.0.1:19876/mcp/oauth/callback avec un code d’autorisation à usage unique en paramètre. Pas de jeton ici — juste un « billet » prouvant que l’utilisateur s’est bien connecté.

5. OpenCode (en arrière-plan) → Auth0

   Le petit serveur local d’OpenCode attrape le code, puis appelle l’endpoint /oauth/token d’Auth0 en présentant : le code + le code_verifier PKCE (preuve que c’est bien la même appli qui a démarré) + la même redirect_uri. Comme l’appli est Native, aucun client secret n’est requis.

6. Auth0 → OpenCode

   Auth0 répond avec deux jetons : l’access token (JWT signé RS256, ~1 h de validité, contient roles2, permissions, aud…) et le refresh token (grâce à offline_access). OpenCode les range dans ~/.local/share/opencode/mcp-auth.json. La page affiche « Authorization successful ».

7. OpenCode → ORDS (chaque appel MCP)

   Dès qu’il faut exécuter un outil SQL, OpenCode appelle http://127.0.0.1:8080/mcp avec Authorization: Bearer <access token>. ORDS est un serveur MCP streamé : il reçoit des appels d’outils, exécute et renvoie les résultats en flux.

8. ORDS (serveur de ressources) — porte 1

   Contrôle global : ORDS valide la signature du jeton via la clé publique Auth0 (JWKS), vérifie iss (Auth0), aud (doit être /mcp), et que la permission …mcpserver:all est présente (dans permissions et/ou scope). Sinon : 401 ou 403.

9. ORDS → bon pool Oracle — porte 2

   Contrôle par pool : ORDS lit la claim roles2 et la compare aux pools déclarés. Pool mcp-hr exige POOL.HR, pool mcp-fin exige POOL.FIN. L’utilisateur ne voit que les pools correspondant à ses rôles — les autres renvoient 403.

10. ORDS → Oracle

    En interne, ORDS se connecte à la base avec un utilisateur technique least-privilege (HR_MCP_RO, FIN_MCP_RO — lecture seule). Le SQL demandé est exécuté et le résultat remonte à OpenCode, donc à l’utilisateur.

Côté OpenCode (docs/OPENCODE.md)

Le jeton décodé, et comment le vérifier

Une fois connecté, on peut lire son jeton. Payload d’un utilisateur qui n’a que le rôle POOL.FIN avec la permission MCP :

{
  "iss": "https://dev-xxxx.us.auth0.com/",     // signé par Auth0 (trailing slash !)
  "aud": "http://127.0.0.1:8080/mcp",        // destiné à ORDS /mcp, exactement
  "sub": "google-oauth2|1023…",            // qui est l'utilisateur
  "roles2": ["POOL.FIN"],                  // rôle → quel(s) pool(s)
  "permissions": ["urn:oracle:dbtools:ords:mcpserver:all"],
  "scope": "urn:oracle:dbtools:ords:mcpserver:all offline_access"
}

Inspecter le token depuis le terminal

python3 - <<'PY'
import json
from pathlib import Path
from jose import jwt  # pip install python-jose si besoin

path = Path.home() / ".local/share/opencode" / "mcp-auth.json"
data = json.loads(path.read_text())
at = data["ords-mcp"]["tokens"]["accessToken"]
c = jwt.get_unverified_claims(at)
print("sub        ", c.get("sub"))
print("aud        ", c.get("aud"))
print("roles2     ", c.get("roles2"))
print("permissions", c.get("permissions"))
print("scope      ", c.get("scope"))
PY

Ce que signifient les messages

Fallback manuel (dev uniquement)

Si OAuth est bloqué, on peut coller un jeton valide en config :

// opencode.json
"oauth": false,
"headers": { "Authorization": "Bearer {env:ORDS_MCP_TOKEN}" }
# export ORDS_MCP_TOKEN='…' puis opencode

Préférer le vrai OAuth pour le lab.