Skip to main content
L’autorisation à granularité fine va au-delà du simple contrôle d’accès fondé sur les permissions : elle permet de mettre en place des modèles d’autorisation sophistiqués qui reposent sur les relations entre les utilisateurs, les rôles, les groupes et les ressources. Ce démarrage rapide montre comment utiliser Auth0 FGA pour mettre en œuvre le contrôle d’accès basé sur les relations (ReBAC) dans les outils de votre serveur MCP. L’application d’exemple illustre cinq modèles d’autorisation :
  1. Outils publics - Accessibles à tous les utilisateurs authentifiés, sans autorisation supplémentaire
  2. Accès basé sur les rôles - Outils attribués à des rôles précis (admin, content_editor)
  3. Appartenance à un groupe - Les utilisateurs héritent des autorisations de leurs groupes (gestionnaires, marketing)
  4. Accès temporaire - Accès aux outils limité dans le temps, avec expiration automatique
  5. Autorisations propres aux ressources - Contrôle à granularité fine des fonctionnalités des outils (p. ex., consultation de documents privés)
À la fin de ce démarrage rapide, vous disposerez d’un serveur MCP qui :
  • Authentifie les utilisateurs avec Auth0 OAuth 2.0
  • Utilise Auth0 FGA pour déterminer à quels outils chaque utilisateur peut accéder
  • Filtre dynamiquement la liste des outils en fonction des autorisations de l’utilisateur
  • Prend en charge des accès temporaires qui expirent automatiquement
  • Fournit des données différentes selon le rôle de l’utilisateur (documents publics ou privés)

Prerequisites

To continue with this quickstart, you need to have an Auth0 account.
To use the resource parameter in your access tokens and the iss claim to identify your authorization server, you need to enable two toggles in the Auth0 Dashboard:
  1. Navigate to Settings on the left sidebar.
  2. Select Advanced in the top right corner.
  3. Scroll down to the Settings section and enable the following toggles:
    • Resource Parameter Compatibility Profile: Enables support for the resource parameter in authorization requests, allowing access tokens to be scoped to a specific API.
    • Include Issuer in Authorization Responses: Includes the iss parameter identifying the authorization server in authorization responses, helping clients defend against mix-up attacks.
This guide uses Auth0 CLI to configure an Auth0 tenant for secure MCP tool access.
  1. Follow the Auth0 CLI installation instructions.
  2. Log in to your account with the Auth0 CLI:
Confirm you are in the correct tenant by double-checking the tenant domain in the terminal, or run the command below:
If more than one tenant is configured, the default tenant will be indicated by an arrow.
To simplify the process of interacting with the Auth0 CLI, we recommend installing jq. This will allow you to easily parse JSON responses from the CLI.
Installez et configurez maintenant les dépendances de FGA :
This guide uses the OpenFGA CLI to manage authorization models and permissions.
  1. Install the FGA CLI:
  1. Verify the installation:
You’ll need an Auth0 FGA or OpenFGA store to manage fine-grained authorization for your MCP tools.Choose your FGA provider:
  • Auth0 FGA: Fully managed service at fga.dev. Best for production use.
  • OpenFGA: Self-hosted open-source option. Best for local development and testing.
Both options use the same authorization model and API. You can start with OpenFGA locally and migrate to Auth0 FGA for production.
The sample application includes a complete authorization model (fga/model.fga) and initial permission tuples (fga/tuples.yaml) that will be imported using the FGA CLI.

Configurer les paramètres du locataire

To allow third-party clients like MCP Inspector to use a connection such as a username-and-password database or a social connection, you need to promote the connection to a domain-level connection. Learn more about configuring third-party applications.
1

List Your Connection

List your connections to get their IDs
2

Choose Your Connections

From the list, identify which connections you want to use for the MCP server and copy the ID.
  • For the username-and-password database, look for the connection with the strategy auth0.
  • For the Google social connection, look for the connection with the strategy google-oauth2.
3

Upgrade the Connection to Domain-Level

For each of those specific connection IDs, run the following command to mark it as a domain-level connection. Replace YOUR_CONNECTION_ID with the actual ID (e.g., con_XXXXXXXXXXXXXXXX).

Créer une API pour représenter votre serveur MCP

An MCP server is treated just like any other API in your Auth0 tenant, which means you can use the same access control, scoping, and authorization features. The API (also known as a Resource Server) represents your protected MCP Server. Run the following command to create an API in Auth0:
Note that rfc9068_profile_authz is used as the token dialect to include the permissions claim in the access token, which can be useful for the API to check user permissions without making additional calls. For more details on protecting APIs with Auth0, check our quickstarts.
Ce démarrage rapide utilise deux permissions OAuth à titre de démonstration : tool:greet et tool:whoami. L’outil get_datetime est public et ne nécessite aucune permission, tandis que get_documents utilise FGA pour gérer l’autorisation.

Configurer votre magasin FGA

1

Create an Auth0 FGA account

Sign up for a free account at fga.dev.
2

Create a store

In the Auth0 FGA dashboard, create a new store for your MCP server.
3

Generate API credentials

  1. Navigate to Settings in your store.
  2. In the Authorized Clients section, click + Create Client.
  3. Give your client a name and select the following permissions:
    • Read/Write model, changes, and assertions - To query authorization decisions
    • Write and delete tuples - To import tuples (user permissions)
    • Read and query - To import the authorization model
  4. Click Create.
  5. Save the credentials shown in the confirmation modal.
4

Configure environment variables

Set the following environment variables in your terminal. These will be used by the FGA CLI to connect to your store.
Replace the placeholders with the credentials from the previous step. Note that FGA_API_URL may vary based on your region (e.g., api.eu1.fga.dev for Europe).

Application d’exemple

Commencez par télécharger ou cloner l’application d’exemple de ce Démarrage rapide. Cet exemple comprend un serveur MCP FastMCP intégrant Auth0 OAuth et Auth0 FGA en JavaScript/TypeScript.
Une fois le téléchargement terminé, extrayez les fichiers et ouvrez le projet dans l’IDE de votre choix.

Installer les paquets

Installez les dépendances nécessaires :

Créer votre fichier d’environnement

From the root of your sample app directory, run the following command to create a new .env file with your Auth0 configuration:
Next, add your FGA configuration to the .env file. The variables you need depend on which FGA provider you’re using:
Add the following to your .env file using the credentials from your Auth0 FGA store:
.env
Replace:
  • YOUR_STORE_ID with your store ID from the Auth0 FGA dashboard
  • YOUR_CLIENT_ID with your client ID
  • YOUR_CLIENT_SECRET with your client secret
  • Update FGA_API_URL if your store is in a different region (e.g., https://api.eu1.fga.dev for Europe)
Your complete .env file should look like this:
.env

Comprendre le modèle d’autorisation

The authorization model in this sample demonstrates how Auth0 FGA provides fine-grained access control using Relationship-Based Access Control (ReBAC).

Authorization Model Structure

The complete model is defined in fga/model.fga:
The model defines four authorization patterns:
Tools that are accessible to all authenticated users without requiring specific permissions.
The wildcard user:* means any authenticated user can use the get_datetime tool.
Tools are assigned to specific roles, and users with those roles can access the tools.
Users assigned the admin role automatically gain access to these tools.
Users inherit permissions through group membership. Groups are assigned to roles, creating a permission chain.
Permission Chain: User → Group → Role → ToolWhen you add a user to the managers group, they automatically inherit all permissions of the admin role, including access to all tools.
Time-limited access to tools that automatically expires after a specified duration.
When you grant temporal access (e.g., “20 seconds to use the greet tool”), FGA evaluates the condition on each request. Access is automatically revoked when the time expires.
Fine-grained permissions for specific features or data within tools.
The get_documents tool checks this permission separately to determine whether to return private documents. This allows the same tool to provide different data based on user permissions.Example:
  • Admin role: Sees all documents (public + private)
  • Content editor role: Sees only public documents

How Authorization Works

When a user connects to the MCP server:
  1. The server authenticates the user with Auth0 (validates JWT token)
  2. The server queries FGA to get all tools the user can access:
    • Checks can_use relation for each tool
    • Evaluates group memberships, role assignments, and temporal conditions
  3. The server returns only authorized tools to the MCP client
  4. When the user calls a tool like get_documents, the server checks can_view_private_documents to determine what data to return
This approach ensures that authorization decisions are centralized in FGA and can be updated dynamically without changing code.

Importer le modèle d’autorisation et les tuples

L’exemple comprend un modèle d’autorisation complet et des tuples d’autorisation initiaux qui définissent :
  • L’accès public à get_datetime pour tous les utilisateurs
  • Les attributions de rôles (admin, content_editor)
  • Les mappages de groupes vers des rôles (managers → admin, marketing → content_editor)
  • Les autorisations d’accès aux outils pour chaque rôle
1

Examiner le modèle d’autorisation

Le modèle d’autorisation est défini dans fga/model.fga. Il comprend des types pour les utilisateurs, les groupes, les rôles et les outils, ainsi qu’une condition d’accès temporelle.Les tuples initiaux sont définis dans fga/tuples.yaml et établissent les autorisations de base.
2

Importer le modèle et les tuples

À la racine du répertoire de votre application d’exemple, exécutez :
Cette commande permet de :
  1. Créer un nouveau magasin FGA (si vous utilisez OpenFGA localement)
  2. Téléverser le modèle d’autorisation à partir de fga/model.fga
  3. Importer les tuples initiaux à partir de fga/tuples.yaml
  4. Exécuter les tests définis dans fga/store.fga.yaml pour vérifier la configuration
Si vous utilisez OpenFGA, la sortie de la commande comprendra un identifiant de magasin. Copiez cet identifiant et ajoutez-le à votre fichier .env en tant que FGA_STORE_ID. Si vous utilisez Auth0 FGA avec un magasin existant, la commande mettra à jour votre magasin avec le nouveau modèle et les nouveaux tuples.
3

Vérifier l’importation

Si l’importation réussit, vous devriez obtenir une sortie semblable à celle-ci :
À la fin, les tests devraient indiquer que toutes les vérifications ont réussi, ce qui confirme que le modèle d’autorisation fonctionne correctement.
Si vous utilisez Auth0 FGA, vous pouvez consulter et gérer votre modèle d’autorisation dans le Dashboard Auth0 FGA. Le Dashboard offre un explorateur de modèle visuel et vous permet de consulter, d’ajouter et de supprimer des tuples en temps réel.

Exécuter le serveur MCP

Démarrez le serveur MCP :
Le serveur démarrera sur le port 3001 (ou sur le port indiqué dans votre fichier .env). La console devrait afficher des messages indiquant que :
  • le serveur a bien démarré;
  • le client FGA a été initialisé;
  • le serveur est à l’écoute des connexions à l’adresse http://localhost:3001/mcp.
Laissez le serveur en cours d’exécution : vous en aurez besoin pour les tests des sections suivantes.

Gérer les autorisations des utilisateurs

The sample application includes helper scripts in the fga/ directory to make permission management easier. These scripts use the FGA CLI to add or remove authorization tuples dynamically.

Available Scripts

Grant a user all permissions associated with a group (and its assigned role).Usage:
Examples:
What it does: Creates an FGA tuple that makes the user a member of the specified group. Since groups are assigned to roles, the user automatically inherits all role permissions.Available groups:
  • managers - Assigned to admin role (all tools + private documents)
  • marketing - Assigned to content_editor role (all tools, public documents only)
Revoke a user’s group membership and all associated permissions.Usage:
Example:
What it does: Deletes the FGA tuple that grants group membership. The user immediately loses all permissions from that group’s role.
Provide time-limited access to a specific tool that automatically expires.Usage:
Examples:
What it does: Creates an FGA tuple with a temporal condition. FGA evaluates the condition on each request and automatically denies access when the duration expires. No cleanup is needed.Supported durations: Use standard time notation (s for seconds, m for minutes, h for hours).Available tools: greet, whoami, get_documents
Public tools like get_datetime don’t need temporal access grants since they’re already accessible to all authenticated users.
Reset all tuples to the initial state defined in fga/tuples.yaml.Usage:
What it does: Deletes all existing tuples and reimports the default tuples from fga/tuples.yaml. Useful for returning to a clean state during testing.
This script removes all user assignments, including any custom permissions you’ve added. Use with caution.

Testing Permission Changes

After running any of these scripts, you need to reload the tools:
  • for MCP inspector: click ‘Clear’ in the MCP inspector tools panel and then ‘List Tools’
  • for other MCP clients: you might need to reconnect the MCP Client to see the updated tool list.
The server queries FGA on each connection to determine available tools.
You can also manage tuples directly in the Auth0 FGA Dashboard if you’re using Auth0 FGA. The dashboard provides a visual interface for viewing, adding, and removing authorization tuples in real-time.

Testing your MCP server

Now that your MCP server is up and running, you can test it by using tools like MCP Inspector.

Learn how to test your Auth0-powered MCP server

Tester les scénarios d’autorisation

Testez maintenant différents scénarios d’autorisation pour voir comment FGA contrôle l’accès aux outils. Vous devrez utiliser un client MCP comme MCP Inspector pour vous connecter à votre serveur.
1

Tester l’accès de base

Connectez-vous à votre serveur MCP avec vos informations d’identification d’utilisateur. Au départ, seul l’outil public devrait s’afficher.Outils attendus : get_datetimeOn constate ainsi que, sans attribution de rôle ni de groupe, les utilisateurs authentifiés n’ont accès qu’aux outils publics.
2

Accorder l’accès administrateur au moyen du groupe managers

Ajoutez votre utilisateur au groupe managers pour lui accorder les autorisations du rôle administrateur :
Remplacez YOUR_EMAIL par l’adresse courriel que vous utilisez pour vous authentifier.Reconnectez-vous dans votre client MCP et vérifiez que tous les outils s’affichent maintenant.Outils attendus : get_datetime, greet, whoami, get_documentsAppelez l’outil get_documents et vérifiez que la réponse contient à la fois les documents publics et privés. On voit ainsi des autorisations propres aux ressources, fondées sur le rôle administrateur.
Dans MCP Inspector, vous devrez vous déconnecter puis vous reconnecter (ou actualiser la connexion) après avoir modifié les autorisations. Le serveur interroge FGA à chaque nouvelle connexion pour déterminer les outils disponibles.
3

Tester le rôle d’éditeur de contenu

Passez du rôle administrateur à celui d’éditeur de contenu en modifiant l’appartenance aux groupes :
Reconnectez-vous dans votre client MCP.Outils attendus : get_datetime, greet, whoami, get_documentsAppelez l’outil get_documents et vérifiez que seuls les documents publics s’affichent désormais (aucun document privé). On voit ainsi comment un même outil peut fournir des données différentes selon le rôle de l’utilisateur.Différence clé : les éditeurs de contenu ont accès aux mêmes outils que les administrateurs, mais ne disposent pas de l’autorisation can_view_private_documents.
4

Tester l’accès temporaire

Retirez toutes les appartenances aux groupes et accordez un accès limité dans le temps à un outil précis :
Cette commande accorde un accès de 20 secondes à l’outil greet.Reconnectez-vous immédiatement dans votre client MCP.Outils attendus : get_datetime, greetAppelez l’outil greet pour vérifier qu’il fonctionne.Attendez 25 secondes, puis reconnectez-vous.Outils attendus : get_datetime (seulement)L’outil greet ne devrait plus apparaître. On constate ainsi que l’accès temporaire expire automatiquement, sans aucun nettoyage nécessaire.
L’accès temporaire est évalué en temps réel à chaque requête. Une fois la durée écoulée, FGA refuse automatiquement l’accès, même si le tuple existe toujours dans la base de données.

Prochaines étapes