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

# MastraAuthWorkos クラス

`MastraAuthWorkos` クラスは、WorkOS を使用して Mastra の認証を提供します。WorkOS アクセストークンを使用して受信リクエストを検証し、`auth` オプションを介して Mastra サーバーと統合します。

## 使用例

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
  },
})
```

> **注記:** 必要な環境変数（`WORKOS_API_KEY` と `WORKOS_CLIENT_ID`）が設定されている場合は、コンストラクターパラメーターを省略できます。その場合は、引数なしで `new MastraAuthWorkos()` を使用します。

## コンストラクターパラメーター

**apiKey** (`string`): WorkOS API キー。ユーザー検証と組織管理のために WorkOS API で認証する際に使用されます。 (Default: `process.env.WORKOS_API_KEY`)

**clientId** (`string`): WorkOS Client ID。認可コードをアクセストークンと交換する際に、アプリケーションを識別します。 (Default: `process.env.WORKOS_CLIENT_ID`)

**name** (`string`): Auth Provider インスタンスのカスタム名。 (Default: `"workos"`)

**redirectUri** (`string`): WorkOS AuthKit が使用する OAuth リダイレクト URI。組み込みの WorkOS サインインフローを使用する場合に設定します。 (Default: `process.env.WORKOS_REDIRECT_URI`)

**fetchMemberships** (`boolean`): 認証中に組織メンバーシップを読み込みます。MastraFGAWorkos を使用し、FGA チェックで正しい組織メンバーシップ ID を解決できるようにする場合は、true に設定します。 (Default: `false`)

**trustJwtClaims** (`boolean`): workos.userManagement.getUser() が適用されない場合でも WorkOSUser を構築できるよう、検証済み Bearer トークンのクレームを信頼します。WorkOS のカスタム JWT テンプレートを基盤とするサービスアカウントまたはマシン間トークンに使用します。 (Default: `false`)

**jwtClaims** (`{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }`): 検証済み Bearer JWT クレームを、認証済みの WorkOSUser にマッピングします。organizationMembershipId やその他の FGA 固有のクレームを含むカスタム JWT テンプレートに便利です。

## 環境変数

コンストラクターオプションが指定されていない場合、次の環境変数が自動的に使用されます。

**WORKOS\_API\_KEY** (`string`): WorkOS API キー。WorkOS Dashboard の API Keys で確認できます。

**WORKOS\_CLIENT\_ID** (`string`): WorkOS Client ID。WorkOS Dashboard の Applications で確認できます。

**WORKOS\_REDIRECT\_URI** (`string`): 組み込みのセッションベースフローを使用する場合に WorkOS AuthKit が使用する OAuth リダイレクト URI。

## デフォルトの認可動作

デフォルトでは、`MastraAuthWorkos` は、解決されたユーザーオブジェクトに `id` と `workosId` の両方が含まれるすべての認証済み WorkOS ユーザーを認可します。

1. **トークンの検証**：アクセストークンを WorkOS で検証し、有効かつ期限切れでないことを確認します
2. **ユーザー情報の取得**：検証済みトークンからユーザー情報を抽出します
3. **認可の判定**：解決されたユーザーに必要な識別子が含まれている場合、アクセスを許可します

デフォルトでは、`MastraAuthWorkos` はロールゲートではなく Auth Provider として機能します。

## FGA メンバーシップの読み込み

`MastraFGAWorkos` を使用する場合は、`fetchMemberships: true` を設定します。これにより、認証中にユーザーの WorkOS 組織メンバーシップが読み込まれ、FGA チェックで正しい組織メンバーシップ ID を解決できるようになります。

`fetchMemberships` が `false` の場合、Mastra は認証済みリクエストごとに追加で行う WorkOS の `listOrganizationMemberships()` 呼び出しを省略します。

## サービストークンと JWT クレーム

WorkOS JWT テンプレートにカスタムクレームが含まれている場合、それらを認証済みの `WorkOSUser` に直接マッピングできます。

```typescript
import { MastraAuthWorkos } from '@mastra/auth-workos'

const auth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: process.env.WORKOS_REDIRECT_URI,
  trustJwtClaims: true,
  jwtClaims: {
    organizationId: 'org_id',
    organizationMembershipId: 'urn:mastra:organization_membership_id',
  },
})
```

`trustJwtClaims` が有効な場合、`getUser()` が適切な検索方法でなくても、Mastra はサービスプリンシパル用の検証済み Bearer トークンを認証できます。これは、マシン間フローの FGA チェックに、事前解決済みの `organizationMembershipId` 値を渡すための推奨方法です。

## カスタム認可

より厳格な認可が必要な場合は、`MastraAuthWorkos` をサブクラス化し、`authorizeUser()` をオーバーライドします。

```typescript
import { MastraAuthWorkos } from '@mastra/auth-workos'
import type { HonoRequest } from 'hono'

class AdminOnlyWorkosAuth extends MastraAuthWorkos {
  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
    return user?.metadata?.role === 'admin'
  }
}
```

## WorkOS ユーザー型

`authorizeUser()` やその他の WorkOS Auth フック内で使用できる `WorkOSUser` 型には、Mastra の正規化されたユーザーフィールドと WorkOS 固有のメタデータが含まれます。WorkOS では管理者がカスタム JWT テンプレートを設定することもできるため、正確な構造は設定によって異なる場合があります。次の例は、WorkOS を基盤とするユーザーオブジェクトの例です。

```javascript
{
  'urn:myapp:full_name': 'John Doe',
  'urn:myapp:email': 'john.doe@example.com',
  'urn:myapp:organization_tier': 'bronze',
  'urn:myapp:user_language': 'en',
  'urn:myapp:organization_domain': 'example.com',
  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
  sub: 'user_01XYZ789ABC123DEF456GHI012',
  sid: 'session_01PQR456STU789VWX012YZA345',
  jti: '01MNO678PQR901STU234VWX567',
  org_id: 'org_01DEF234GHI567JKL890MNO123',
  role: 'member',
  roles: [ 'member' ],
  permissions: [],
  exp: 1758290589,
  iat: 1758290289
}
```

`urn:myapp:` プレフィックスを持つプロパティは、WorkOS JWT テンプレートで設定されたカスタムクレームです。標準の JWT クレームには、`sub`（ユーザー ID）、`iss`（発行者）、`exp`（有効期限）のほか、`org_id`、`role`、`roles` などの WorkOS 固有のクレームが含まれます。

## 関連項目

[MastraAuthWorkos クラス](https://mastra.zisheng.pro/ja/docs/server/auth/workos)