MastraAuthWorkos クラス
MastraAuthWorkos クラスは、WorkOS を用いて Mastra の認証を提供します。WorkOS のアクセストークンで受信リクエストを検証し、experimental_auth オプションを介して Mastra サーバーと統合します。
使い方の例
import { Mastra } from "@mastra/core/mastra";
import { MastraAuthWorkos } from '@mastra/auth-workos';
export const mastra = new Mastra({
// ..
server: {
experimental_auth: new MastraAuthWorkos({
apiKey: process.env.WORKOS_API_KEY,
clientId: process.env.WORKOS_CLIENT_ID
}),
},
});注意: 適切な名前の環境変数（
WORKOS_API_KEYとWORKOS_CLIENT_ID）が設定されていれば、コンストラクターのパラメータは省略できます。その場合は、引数なしでnew MastraAuthWorkos()を使用してください。
コンストラクターのパラメーター
apiKey?:
clientId?:
name?:
環境変数
コンストラクターのオプションが指定されていない場合、次の環境変数が自動的に使用されます:
WORKOS_API_KEY?:
WORKOS_CLIENT_ID?:
デフォルトの認可動作
デフォルトでは、MastraAuthWorkos は管理者アクセスを判定するロールベースの認可を実装します。
- トークンの検証: アクセストークンが有効で期限切れでないことを確認するため、WorkOS で検証します
- ユーザー情報の取得: 検証済みトークンからユーザー情報を抽出します
- 組織メンバーシップの確認: ユーザー ID に紐づくすべての組織メンバーシップを WorkOS に問い合わせます
- ロールの抽出: 組織メンバーシップからすべてのロールを収集します
- 管理者チェック: いずれかのロールにスラッグ「admin」が含まれるかを確認します
- 認可の判定: 少なくとも1つの組織でユーザーが管理者ロールを持っている場合にのみアクセスを許可します
つまり、デフォルトでは少なくとも1つの組織で管理者権限を持つユーザーのみが、Mastra のエンドポイントへアクセスできます。
カスタムの認可ロジック（例: 認証済みユーザー全員を許可、特定のロールの確認、独自のビジネスロジックの実装）を用いるには、authorizeUser 関数をカスタマイズして提供してください。
WorkOS ユーザータイプ
authorizeUser 関数で使用される WorkosUser 型は、WorkOS が返す JWT トークンのペイロードに対応します。WorkOS では管理者がカスタムの JWT テンプレートを設定できるため、具体的な構造は設定によって異なる場合があります。ユーザーオブジェクトの例は次のとおりです：
{
'urn:myapp:full_name': 'John Doe',
'urn:myapp:email': 'john.doe@example.com',
'urn:myapp:organization_tier': 'bronze',
'urn:myapp:user_language': 'ja',
'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（有効期限）があり、WorkOS 固有のクレームとして org_id、role、roles などがあります。