Skip to main content
きめ細かな認可 (Fine-grained authorization) は、ユーザー、ロール、グループ、リソース間の関係に基づく高度な権限モデルを実現し、単純なスコープベースのアクセス制御よりも柔軟な制御を可能にします。このクイックスタートでは、Auth0 FGAを使用して、MCPサーバーのツールに関係ベースのアクセス制御 (ReBAC) を実装する方法を説明します。 サンプルアプリケーションでは、次の5つの認可パターンを紹介します。
  1. パブリックツール - 追加の権限がなくても、認証済みのすべてのユーザーがアクセス可能
  2. ロールベースのアクセス - 特定のロール (admin、content_editor) に割り当てられたツール
  3. グループメンバーシップ - ユーザーはグループ (managers、marketing) への所属を通じて権限を継承
  4. 時間制限付きアクセス - 期限が来ると自動的に失効する、期間限定のツールアクセス
  5. リソース固有の権限 - ツール機能に対するきめ細かな制御 (例:非公開ドキュメントの閲覧)
このクイックスタートを完了すると、次の機能を備えたMCPサーバーが完成します。
  • Auth0 OAuth 2.0でユーザーを認証する
  • Auth0 FGAを使用して、各ユーザーがアクセスできるツールを判定する
  • ユーザーの権限に応じてツール一覧を動的に絞り込む
  • 自動的に失効する期間限定のアクセス権の付与をサポートする
  • ユーザーのロールに応じて異なるデータ (公開ドキュメントと非公開ドキュメント) を提供する

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.
次に、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.

テナント設定を構成する

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).

MCPサーバーを表すAPIを作成する

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.
このクイックスタートでは、デモ用にtool:greetとtool:whoamiの2つのOAuthスコープを使用します。get_datetimeツールはパブリックなためスコープは不要です。一方、get_documentsはFGAを使って認可を行います。

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).

サンプルアプリ

まず、このクイックスタート用のサンプルアプリをダウンロードまたはクローンしてください。このサンプルには、Auth0 OAuthとAuth0 FGAを統合した、JavaScript/TypeScript製のFastMCP MCPサーバーが含まれています。
ダウンロードしたらファイルを展開し、お好みのIDEでプロジェクトを開いてください。

パッケージのインストール

必要な依存関係をインストールします。

環境ファイルを作成する

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

認可モデルについて

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.

認可モデルとタプルをインポートする

このサンプルには、完全な認可モデルと初期の権限タプルが含まれており、次の内容が定義されています。
  • すべてのユーザーに対する get_datetime へのパブリックアクセス
  • ロールの割り当て (admin、content_editor)
  • グループとロールのマッピング (managers → admin、marketing → content_editor)
  • 各ロールのツールアクセス権限
1

認可モデルを確認する

認可モデルは fga/model.fga で定義されています。ユーザー、グループ、ロール、ツールの型に加え、時間制限付きアクセスの条件が含まれています。初期タプルは fga/tuples.yaml で定義されており、ベースとなる権限を設定します。
2

モデルとタプルをインポートする

サンプルアプリのディレクトリのルートで、次のコマンドを実行します。
このコマンドは次の処理を行います。
  1. 新しい FGA ストアを作成する (OpenFGA をローカルで使用している場合)
  2. fga/model.fga の認可モデルをアップロードする
  3. fga/tuples.yaml の初期タプルをインポートする
  4. fga/store.fga.yaml で定義されたテストを実行し、設定を検証する
OpenFGA を使用している場合は、コマンドの出力にストア ID が含まれます。この ID をコピーし、.env ファイルに FGA_STORE_ID として追加してください。Auth0 FGA で既存のストアを使用している場合は、新しいモデルとタプルでストアが更新されます。
3

インポートを確認する

インポートが成功すると、次のような出力が表示されます。
最後に実行されるテストですべてのチェックが成功していれば、認可モデルは正しく機能しています。
Auth0 FGA を使用している場合は、Auth0 FGA ダッシュボードで認可モデルを表示・管理できます。ダッシュボードではビジュアルなモデルエクスプローラーを利用でき、タプルの表示、追加、削除もリアルタイムで行えます。

MCPサーバーを実行する

MCPサーバーを起動します。
サーバーはポート 3001 (または .env ファイルで指定したポート) で起動します。コンソールに、次の内容を示す出力が表示されるはずです。
  • サーバーが正常に起動したこと
  • FGA クライアントが初期化されたこと
  • サーバーが http://localhost:3001/mcp で接続を待ち受けていること
以降のセクションでテストを行うため、サーバーは起動したままにしておいてください。

ユーザー権限を管理する

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

認可シナリオをテストする

次に、さまざまな認可シナリオをテストして、FGAがツールへのアクセスをどのように制御するかを確認します。サーバーへの接続には、MCP InspectorなどのMCPクライアントが必要です。
1

基本アクセスをテストする

ユーザーの認証情報を使用してMCPサーバーに接続します。初期状態では、パブリックツールのみが表示されるはずです。想定されるツール:get_datetimeこのことから、ロールやグループが割り当てられていない場合、認証済みユーザーはパブリックツールにしかアクセスできないことがわかります。
2

managersグループで管理者アクセスを付与する

ユーザーをmanagersグループに追加して、管理者ロールの権限を付与します。
YOUR_EMAILは、認証に使用するメールアドレスに置き換えてください。MCPクライアントで再接続し、すべてのツールが表示されることを確認します。想定されるツール:get_datetime、greet、whoami、get_documentsget_documentsツールを呼び出し、レスポンスにパブリックとプライベートの両方のドキュメントが含まれていることを確認します。これは、管理者ロールに基づくリソース固有の権限が機能していることを示しています。
MCP Inspectorでは、権限を変更した後に切断して再接続する (または接続を更新する) 必要があります。サーバーは新しい接続のたびにFGAに問い合わせて、利用可能なツールを判断します。
3

コンテンツ編集者ロールをテストする

グループのメンバーシップを変更して、管理者からコンテンツ編集者に切り替えます。
MCPクライアントで再接続します。想定されるツール:get_datetime、greet、whoami、get_documentsget_documentsツールを呼び出し、今度はパブリックドキュメントのみが表示される (プライベートドキュメントは表示されない) ことを確認します。このように、同じツールでもユーザーのロールに応じて異なるデータを返すことができます。主な違い:コンテンツ編集者は管理者と同じツールにアクセスできますが、can_view_private_documents権限は持っていません。
4

時間制限付きアクセスをテストする

すべてのグループメンバーシップを削除し、特定のツールへの時間制限付きアクセスを付与します。
これにより、greetツールへの20秒間のアクセスが付与されます。MCPクライアントですぐに再接続します。想定されるツール:get_datetime、greetgreetツールを呼び出して、動作することを確認します。25秒待ってからもう一度再接続します。想定されるツール:get_datetime (のみ)greetツールは表示されなくなっているはずです。このように、時間制限付きアクセスはクリーンアップ作業なしで自動的に失効します。
時間制限付きアクセスは、リクエストごとにリアルタイムで評価されます。期限が切れると、データベースにタプルが残っていても、FGAは自動的にアクセスを拒否します。

次のステップ