MastraAuthWorkos クラス

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

使用例

src/mastra/index.ts

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

= process.env.WORKOS_API_KEY

WorkOS API キー。ユーザー検証と組織管理のために WorkOS API で認証する際に使用されます。

clientId?:

string

= process.env.WORKOS_CLIENT_ID

WorkOS Client ID。認可コードをアクセストークンと交換する際に、アプリケーションを識別します。

name?:

string

= "workos"

Auth Provider インスタンスのカスタム名。

redirectUri?:

string

= process.env.WORKOS_REDIRECT_URI

WorkOS AuthKit が使用する OAuth リダイレクト URI。組み込みの WorkOS サインインフローを使用する場合に設定します。

fetchMemberships?:

boolean

= false

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

trustJwtClaims?:

boolean

= false

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

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 に直接マッピングできます。

src/mastra/auth.ts

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() をオーバーライドします。

src/mastra/auth.ts

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 を基盤とするユーザーオブジェクトの例です。

{
  '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 クラス