> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Fine-Grained Authorization (FGA)

> **注記:** Fine-Grained Authorization は Mastra Enterprise Edition の一部です。本番環境へのデプロイには有効な EE ライセンスが必要です。詳しくは[営業担当へのお問い合わせ](https://mastra.ai/contact)をご利用ください。

Fine-Grained Authorization（FGA）は、Mastra アプリケーションにリソースレベルの権限チェックを追加します。RBAC が「このロールはこのアクションを実行できるか？」に答えるのに対し、FGA は\*\*「このユーザーは、この特定のリソースに対してこのアクションを実行できるか？」\*\*に答えます。

## FGA を使用する状況

FGA は、権限がコンテキストに応じて変わるマルチテナント B2B 製品向けに設計されています。

- あるユーザーが Team A では **admin** でも、Team B では **member** にすぎない場合がある
- スレッドへのアクセスを、ユーザー自身の Organization に限定する必要がある
- Workflow の実行範囲を特定のチームまたはプロジェクトに限定する必要がある
- Tool へのアクセスが、ユーザーとリソースの関係に依存する

## 設定

Mastra サーバー設定で、認証および RBAC とともに FGA を設定します。

```typescript
import { Mastra } from '@mastra/core/mastra';
import { MastraFGAPermissions } from '@mastra/core/auth/ee';
import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos';

const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      /* ... */
      fetchMemberships: true,
      mapUserToResourceId: user => user.teamId,
    }),
    fga: new MastraFGAWorkos({
      resourceMapping: {
        agent: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
        workflow: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
        thread: { fgaResourceType: 'workspace-thread', deriveId: ({ resourceId }) => resourceId },
      },
      permissionMapping: {
        [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows',
        [MastraFGAPermissions.WORKFLOWS_EXECUTE]: 'manage-workflows',
        [MastraFGAPermissions.MEMORY_READ]: 'read',
        [MastraFGAPermissions.MEMORY_WRITE]: 'update',
      },
    }),
    storedResources: {
      scope: true,
    },
  },
});
```

`MastraFGAWorkos` を使用する場合は、`fetchMemberships: true` を `MastraAuthWorkos` に設定します。WorkOS の FGA チェックでは、認可に使用する正しいメンバーシップ ID を解決するために、ユーザーが所属する Organization の情報が必要です。

メモリの認可では、リソースマッピングのキーに `thread` を使用します。`MastraFGAWorkos` は従来のエイリアス `memory` も引き続き受け付けますが、新しい設定では `thread` を優先してください。

`server.fga` を設定すると、Mastra は保護されたアクションに FGA を適用します。保護されたアクションに認証済みユーザーがいない場合、Mastra はそのアクションを拒否します。`server.fga` が設定されていない場合、これらの FGA チェックはスキップされ、Mastra は従来の動作を維持します。

### リソースのマッピング

`resourceMapping` は、リクエストコンテキストから FGA のリソースタイプと ID を解決する方法を Mastra に指示します。キーは Mastra のリソースタイプで、値には FGA のリソースタイプと ID の導出方法を定義します。

```typescript
resourceMapping: {
  // When checking "can user execute agent X?", resolve the FGA resource
  // as the user's team (type: 'team', id: user.teamId)
  agent: {
    fgaResourceType: 'team',
    deriveId: (ctx) => ctx.user.teamId,
  },
}
```

`deriveId()` は次の値を受け取ります。

- `user`: 認証済みユーザー
- `resourceId`: 利用可能な場合は、所有元の Mastra リソース ID（たとえば、スレッドの `resourceId`）
- `requestContext`: 高度なテナント解決に使用する現在のリクエストコンテキスト
- `metadata`: 試行されたアクションに関する Provider 固有のメタデータ

`undefined` を `deriveId()` から返すと、元の Mastra リソース ID にフォールバックします。

スレッドとメモリのチェックでは、Mastra は引き続き未加工の `threadId` をチェック対象のリソースとして渡しますが、スレッドを所有する `resourceId` も `deriveId()` に転送します。これにより、スレッドの権限を `userId-teamId-orgId` のような複合テナント ID にマッピングできます。

### 権限のマッピング

`permissionMapping` は、Mastra 内部の権限文字列を FGA Provider の権限スラッグに変換します。

```typescript
import { MastraFGAPermissions } from '@mastra/core/auth/ee';

permissionMapping: {
  [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows', // Mastra permission -> WorkOS permission slug
  [MastraFGAPermissions.MEMORY_READ]: 'read',
}
```

権限に対応するマッピングがない場合は、元の文字列がそのまま渡されます。

起動時に Mastra が生成する可能性のある権限一式を検証するには、`validatePermissions()` を使用します。すべての Mastra 権限に明示的な Provider の権限スラッグが必要な場合に使用してください。

### 保存済みリソースのスコープ設定

FGA はリソースへのアクセスを認可しますが、共有ストレージ内の保存済みレコードを自動的に絞り込むわけではありません。マルチテナントアプリケーションで組み込みの保存済みリソース API を使用する場合は、保存済みリソースのスコープ設定を有効にします。

```typescript
const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      /* ... */
      mapUserToResourceId: user => user.teamId,
    }),
    storedResources: {
      scope: true,
    },
  },
});
```

`scope: true` を指定すると、Mastra はリクエストコンテキストから `MASTRA_RESOURCE_ID_KEY` を読み取ります。`mapUserToResourceId()` は認証後にこの値を設定します。保存済みリソースのハンドラーはスコープをレコードのメタデータに保持し、一覧取得、読み取り、更新、公開、削除の各操作をそのスコープで絞り込みます。

スコープにカスタムのリクエストロジックが必要な場合は、オブジェクトを使用します。

```typescript
storedResources: {
  scope: {
    metadataKey: 'teamId',
    resolve: ({ user }) => user.teamId,
    requireScope: true,
  },
},
```

`requireScope` が `true` または省略されている場合、スコープを解決できないと、スコープが設定された保存済みリソースのルートは失敗します。

### ルートポリシーの適用範囲

Mastra には、Agent、Workflow、Tool、MCP Tool、メモリスレッド、Response、Conversation、保存済みリソースなどの組み込みリソースルートに対するルートレベルの FGA メタデータが含まれています。保存済みリソースの対象ルートには、`/stored/agents`、`/stored/mcp-clients`、`/stored/prompt-blocks`、`/stored/scorers`、`/stored/skills`、`/stored/workspaces` が含まれます。ルートレベルの `fga` メタデータがある場合、Mastra がそのルートの組み込みメタデータを導出できる場合、または Provider が `resolveRouteFGA()` でメタデータを提供する場合に、そのルートがチェックされます。

FGA メタデータを解決できない保護対象ルートを拒否するには、FGA Provider にルートポリシーの適用範囲を設定します。

```typescript
const fga = new MastraFGAWorkos({
  resourceMapping: {
    project: { fgaResourceType: 'project' },
  },
  permissionMapping: {
    'projects:read': 'read',
  },
  requireForProtectedRoutes: true,
  auditProtectedRoutes: 'warn',
  validatePermissions: async permissions => {
    // Throw if a Mastra permission is missing from permissionMapping.
  },
});
```

保護対象ルートに組み込みの FGA メタデータがない場合に起動を失敗させるには、`auditProtectedRoutes: 'error'` を設定します。`requireForProtectedRoutes` が有効な場合、Mastra はデフォルトでこの監査を警告としてログに記録します。

カスタムルートでは、ルートレベルの `fga` メタデータを優先してください。これにより、認可ポリシーをルートの近くに配置できます。

```typescript
import { createRoute } from '@mastra/server/server-adapter';

export const getProjectRoute = createRoute({
  method: 'GET',
  path: '/projects/:projectId',
  responseType: 'json',
  requiresAuth: true,
  fga: {
    resourceType: 'project',
    resourceIdParam: 'projectId',
    permission: 'projects:read',
  },
  handler: async () => {
    return { project: null };
  },
});
```

ルート、パラメーター、リクエストコンテキストからルートメタデータを一元的に導出する必要がある場合に限り、`resolveRouteFGA()` を使用します。文字列のプレフィックスをチェックするよりも、ルートマップの方が拡張性に優れています。

```typescript
import type { FGARouteConfig, FGARouteResolver } from '@mastra/core/auth/ee';

const routeFGA = {
  'GET /billing/:accountId': {
    resourceType: 'account',
    resourceIdParam: 'accountId',
    permission: 'billing:read',
  },
} satisfies Record<string, FGARouteConfig>;

const resolveRouteFGA: FGARouteResolver = ({ route }) => routeFGA[`${route.method} ${route.path}`];

const fga = new MastraFGAWorkos({
  /* ... */
  resolveRouteFGA,
});
```

## 適用ポイント

FGA Provider を設定すると、Mastra は次のライフサイクルポイントで認可を自動的にチェックします。

| ライフサイクルポイント                                     | チェックされる権限                                    | リソースタイプ                                                     | リソース ID                                                              |
| ----------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| Agent の実行（`generate`、`stream`）                  | `agents:execute`                             | `agent`                                                     | `agentId`                                                            |
| 組み込みの Workflow HTTP 実行ルートと `Workflow.execute()` | `workflows:execute`                          | `workflow`                                                  | `workflowId`                                                         |
| スタンドアロン Tool の実行                                | `tools:execute`                              | `tool`                                                      | `toolName`                                                           |
| Agent Tool の実行                                  | `tools:execute`                              | `tool`                                                      | `${agentId}:${toolName}`                                             |
| MCP Tool の実行                                    | `tools:execute`                              | デフォルトでは `tool`、またはサーバーレベルの `fga.resourceMapping` によるオーバーライド | デフォルトでは `JSON.stringify([serverName, toolName])`、またはサーバーレベルで導出された ID |
| スレッドとメモリへのアクセス                                  | `memory:read`、`memory:write`、`memory:delete` | `thread`                                                    | `threadId`                                                           |
| 保存済みリソースのルート                                    | ルートアクションに対応する保存済みリソースの権限                     | 保存済みリソースのタイプ                                                | ルートのレコード ID、またはコレクションルートの保存済みリソーススコープ                                |
| HTTP リソースルート                                    | ルートごとの設定                                     | ルートごとの設定                                                    | ルートごとの設定                                                             |

OAuth で保護された MCP サーバーでは、HTTP MCP Transport が認証済みデータを `extra.authInfo` として渡します。FGA が有効な Mastra インスタンスに `MCPServer` を登録する場合は、`mapAuthInfoToUser` を設定して、Mastra が `requestContext.get('user')` を設定してから `tools/list` と `tools/call` をチェックできるようにしてください。MCP Tool のチェックで、内部の Agent および Workflow の Tool チェックとは異なるリソースまたは権限のマッピングが必要な場合は、サーバーレベルの `fga` オプションを使用します。[MCPServer の認証コンテキスト](https://mastra.zisheng.pro/ja/reference/tools/mcp-server)を参照してください。

このリリースでは、`createRun().start()`、`resume()`、`restart()` を直接呼び出す SDK 呼び出しは、コア FGA によって個別にはチェックされません。これらの呼び出しは保護されたルートから実行するか、アプリケーションコードでガードしてください。保護されたエントリーポイントを直接呼び出す場合は、認証済みユーザーを含む `requestContext` を渡します。

コアの Agent、内部 Workflow、Tool、メモリのチェックでは、`requestContext` とアクションのメタデータも FGA Provider に渡します。ルートのチェックでは `requestContext` を渡します。スレッドのチェックでは、利用可能な場合は所有元の `resourceId` を渡します。

## カスタム FGA Provider

任意の FGA バックエンドを使用するには、`IFGAProvider` を実装します。

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  async check(user: any, params: FGACheckParams): Promise<boolean> {
    // Your authorization logic
    return true
  }

  async require(user: any, params: FGACheckParams): Promise<void> {
    const allowed = await this.check(user, params)
    if (!allowed) {
      throw new FGADeniedError(user, params.resource, params.permission)
    }
  }

  async filterAccessible<T extends { id: string }>(
    user: any,
    resources: T[],
    resourceType: string,
    permission: MastraFGAPermissionInput,
  ): Promise<T[]> {
    // Filter resources the user can access
    return resources
  }
}
```

> **注記:** [`IFGAProvider` リファレンス](https://mastra.zisheng.pro/ja/reference/auth/fga)で、すべてのメソッド、パラメーター、`ActorSignal` 型を確認できます。

## システムアクター

自律型 Agent とスケジュール実行される Agent は、エンドユーザーなしで動作します。FGA がユーザーリクエストと区別できるよう、これらの呼び出しにアクターシグナルを付けます。

- `true` または `{ actorKind: 'system' }` は、匿名のシステムアクターを示します。
- オブジェクト形式では、動作する Agent を識別して制約するために、`agentId`、`permissions`、`scope` も指定できます。

デフォルトでは、信頼されたアクターはテナントスコープのチェック後、ユーザーを中心とした `require()` チェックをスキップします。Agent ごとに最小権限を適用するには、Provider にオプションの `requireActor` メソッドを実装します。このメソッドはアクターと `FGACheckParams`（`require` と同じもの）を受け取り、拒否する場合は `FGADeniedError` をスローします。Provider が `requireActor` を実装していない場合は、信頼されたアクターのバイパスが維持されるため、この機能の追加には後方互換性があります。

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  // ...check, require, filterAccessible...

  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
    const agentId = actor === true ? undefined : actor.agentId
    // Resolve the agent's real grants from a trusted source keyed by agentId.
    const granted = await this.grantsForAgent(agentId)
    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
    if (!required.some(permission => granted.includes(permission))) {
      throw new FGADeniedError(null, params.resource, params.permission)
    }
  }
}
```

### 信頼に関する要件

アクターシグナルは信頼された入力であるため、サーバー側で構築してください。

- `actor` は呼び出しごとのシグナルとして扱います。Durable Workflow は実行開始時にこの値を転送しますが、再開時には最初のアクターを復元しません。信頼された再開のたびに明示的に渡すか、Agent の `defaultOptions` で新しいアクターを解決してください。現在のアクターがない場合はユーザー認可が適用され、ユーザーがいなければ閉じる側に倒れて失敗します。
- Mastra は、組み込みの Agent HTTP ルートが処理する実行オプションから `actor` を取り除きます。クライアント入力ではなく、スケジュールジョブや Workflow などのサーバー側コードで設定してください。
- テナントスコープはサーバー側で確立します。組み込みの Agent HTTP ルートは、クライアントがリクエストコンテキストで渡した `organizationId` を無視し、信頼されたアクターのパスでは `organizationId` の設定が必須です。
- Durable Resume では、既存のリクエストコンテキストの復元とマージ動作が維持されます。これによって、永続化されたアクターが後続の Workflow セグメントで信頼されるわけではありません。
- テナントスコープのチェックでは、信頼された `organizationId` が存在することを確認します。`actor.agentId` がその Organization に属しているかは検証しません。この関係が重要な場合は、信頼できる Provider のデータを使用して `requireActor` で検証してください。
- `actor.permissions` は未検証のクレームとして扱います。信頼できるソースから正式な権限を解決してください。最小権限を適用する Provider では、インラインの値を信頼せず、たとえば `agentId` をキーとするマニフェストや FGA バックエンドなど、信頼できるソースから Agent の正式な権限を解決します。
- Provider が `requireActor` を実装すると、このメソッドのエラーによって実行が停止します。Mastra は Organization のみによる認可へフォールバックしません。

## 関連項目

- [`IFGAProvider` リファレンス](https://mastra.zisheng.pro/ja/reference/auth/fga)
- [認証の概要](https://mastra.zisheng.pro/ja/docs/server/auth)
- [WorkOS 認証](https://mastra.zisheng.pro/ja/docs/server/auth/workos)