Configurer Auth0 pour ORDS MCP

Les étapes

Étape par étape

1 · Dashboard et domaine

• Ouvrir manage.auth0.com et choisir/créer un tenant.
• Noter le Domain (menu tenant, en haut à gauche), ex. dev-xxxx.us.auth0.com → c’est AUTH0_DOMAIN.

2 · L’API (resource server)

OpenCode envoie resource=http://127.0.0.1:8080/mcp : Auth0 ne l’accepte que si une API existe avec cet Identifier.

• Menu : Applications → APIs (l’API de niveau supérieur, pas dans une application).
• + Create API avec : Name ORDS MCP Local, Identifier http://127.0.0.1:8080/mcp, Signing Algorithm RS256.
• Copier précisément : http (pas https), 127.0.0.1 (pas localhost), :8080, /mcp, pas de slash final.

2a · La permission

API → Permissions → Add : urn:oracle:dbtools:ords:mcpserver:all (« ORDS MCP global access »).

2b · Réglages de l’API

2c · Au sujet de « APIs » sur l’application Native

3 · Les rôles + la permission sur chaque rôle (critique)

Menu : User Management → Roles. Créer deux rôles dont les noms correspondent exactement aux mcp.role ORDS :

Pour chacun des deux rôles : onglet Permissions → Add Permissions → API ORDS MCP Local → cocher urn:oracle:dbtools:ords:mcpserver:all → Add.

4 · L’application Native (OpenCode)

Menu : Applications → Applications → Create Application. Nom ex. OpenCode Native, type Native. Ne pas utiliser Machine to Machine (pas de login navigateur).

Advanced Settings → Grant Types : Authorization Code = On, Refresh Token = On (recommandé), Client Credentials = Off pour Native (normal).

5 · L’Action Trigger : écrire les rôles dans roles2

Auth0 réserve roles : la liste personnalisée doit porter un autre nom. Dans l’UI, c’est Actions → Triggers.

1. Actions → Library → Build Custom
2. Trigger : Login / Post Login — nom ORDS MCP roles2

/**
 * Auth0 réserve "roles". ORDS lit "roles2" (MCP_ROLE_CLAIM=/roles2).
 * event.authorization.roles est rempli quand RBAC est activé et
 * que des rôles sont assignés à l'utilisateur.
 */
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  api.accessToken.setCustomClaim("roles2", roles);
};

5. Deploy
6. Actions → Triggers → post-login → ajouter l’action au pipeline → Apply

5b · credentials-exchange (optionnel, M2M / scripts/test_auth0.py)

Si on utilise une app Machine to Machine séparée pour les tests automatisés, attacher aussi au trigger credentials-exchange :

exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("roles2", ["POOL.HR", "POOL.FIN"]);
};

Puis autoriser cette app M2M sur l’API avec la permission MCP.

6 · Les utilisateurs

Menu : User Management → Users.

L’onglet Roles sur l’utilisateur assigne le rôle. Les Permissions sur le rôle (étape 3) fournissent le permissions du jeton.

7 · Le .env du lab

AUTH0_DOMAIN=dev-xxxx.us.auth0.com
AUTH0_AUDIENCE=http://127.0.0.1:8080/mcp
AUTH0_CLIENT_ID=<Client ID de l'app Native>
# Pas d'AUTH0_CLIENT_SECRET pour Native + PKCE OpenCode

MCP_ROLE_CLAIM=/roles2

ORACLE_PWD=OracleFree123
ORDS_MODE=mcp
ORDS_HTTP_PORT=8080
ORDS_ENABLE_HTTPS=false

8 · Démarrer la pile

Le premier boot exécute sql/01_lab_schemas.sql dans un nouveau volume Oracle.

docker compose up -d --build
docker compose ps

Si l’audience/issuer Auth0 a changé alors qu’ORDS avait déjà tourné :

docker compose stop ords && docker compose rm -f ords
docker volume rm ords_ords-config
docker compose up -d ords

Modèle mental

Récapitulatif en une image

Utilisateur (+ login Google ou DB)
  + rôle Auth0 POOL.FIN
  + permission du rôle : urn:oracle:dbtools:ords:mcpserver:all
  + Action post-login → roles2
        │
        ▼
Access token
  aud         = http://127.0.0.1:8080/mcp
  roles2      = ["POOL.FIN"]
  permissions = ["urn:oracle:dbtools:ords:mcpserver:all"]
        │
        ▼
ORDS /mcp
  → MCP autorisé
  → database_list = [mcp-fin] seulement

Revoir la séquence OAuth Passer au démarrage complet →