MastraAuthGoogle クラスと MastraRBACGoogle クラス

MastraAuthGoogle クラス

MastraAuthGoogle クラスは、Google Workspace を使用した認証を Mastra に提供します。暗号化されたセッション Cookie を使用する OAuth 2.0 / OIDC ログインフローを実装し、Google ID トークンを検証して、auth オプションを使用して Mastra サーバーと統合します。

使用例

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      redirectUri: process.env.GOOGLE_REDIRECT_URI,
      allowedDomains: ['example.com'],
    }),
  },
})

注記

必要な環境変数が設定されている場合は、コンストラクターのパラメーターを省略できます。その場合は、引数なしで new MastraAuthGoogle() を使用します。

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

clientId?:

string

= process.env.GOOGLE_CLIENT_ID

Google OAuth クライアント ID。

clientSecret?:

string

= process.env.GOOGLE_CLIENT_SECRET

Google OAuth クライアントシークレット。Studio SSO に必要です。

redirectUri?:

string

= process.env.GOOGLE_REDIRECT_URI

SSO コールバック用の OAuth リダイレクト URI。Google Cloud OAuth クライアントで設定したリダイレクト URI と一致する必要があります。

scopes?:

string[]

= ['openid', 'profile', 'email']

ログインフロー中に要求する OAuth スコープ。

allowedDomains?:

string | string[]

= process.env.GOOGLE_ALLOWED_DOMAINS

許可する Google Workspace ホストドメイン。Mastra は、検証済みの hd クレームと照合します。

hostedDomain?:

string

= process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain

Google に hd として渡すホストドメインのログインヒント。これはヒントにすぎず、認可には使用されません。

session?:

GoogleSessionOptions

セッション Cookie の設定。

GoogleSessionOptions

cookieName?:

string

セッション Cookie の名前。

cookieMaxAge?:

number

Cookie の最大有効期間（秒）。

cookiePassword?:

string

セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。設定しない場合、開発環境では自動生成された値が使用されますが、再起動後は保持されません。

secureCookies?:

boolean

セッション Cookie に Secure フラグを設定します。

name?:

string

= 'google'

認証 Provider インスタンスのカスタム名。

環境変数

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

GOOGLE_CLIENT_ID:

string

Google Cloud OAuth クライアントの Google OAuth クライアント ID。

GOOGLE_CLIENT_SECRET?:

string

Google OAuth クライアントシークレット。SSO 認可コードフローに必要です。

GOOGLE_REDIRECT_URI?:

string

SSO コールバック用の OAuth リダイレクト URI。

GOOGLE_COOKIE_PASSWORD?:

string

セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。

GOOGLE_ALLOWED_DOMAINS?:

string

許可する Google Workspace ホストドメインのカンマ区切りリスト。

GOOGLE_HOSTED_DOMAIN?:

string

SSO ログイン時に Google に渡すホストドメインのログインヒント。

認証フロー

MastraAuthGoogle は、次の順序でリクエストを認証します。

1. セッション Cookie。 SSO が有効な場合、Provider は暗号化されたセッション Cookie を読み取り、復号します。有効期限内の有効なセッションによってユーザーが認証されます。
2. Google ID トークンへのフォールバック：有効なセッション Cookie がない場合、Authorization ヘッダーのトークンを Google の JWKS エンドポイントに対して検証します。

認証後、authorizeUser はユーザーに有効な Google ユーザー ID があること、トークンから取得した有効期限を過ぎていないこと、およびドメインが設定されている場合はユーザーの検証済み hd クレームが allowedDomains と一致することを確認します。

認証メソッド

authenticateToken(token, request?)

Google ID トークンを認証します。SSO が有効な場合、このメソッドは Bearer トークンを検証する前に、暗号化されたセッション Cookie を確認します。

const user = await auth.authenticateToken(idToken, request)

戻り値：Promise<GoogleUser | null>

getCurrentUser(request)

セッション Cookie または Bearer Google ID トークンから認証済みユーザーを返します。

const user = await auth.getCurrentUser(request)

戻り値：Promise<GoogleUser | null>

authorizeUser(user)

ユーザーに ID があり、有効期限が切れておらず、ドメインが設定されている場合は allowedDomains と一致するときに true を返します。

const allowed = auth.authorizeUser(user)

戻り値：boolean

getUser(userId)

null を返します。Google ID トークンは直接検証されるため、この Provider は ID によるユーザー検索を行いません。

const user = await auth.getUser(userId)

戻り値：Promise<GoogleUser | null>

GoogleUser 型

GoogleUser 型は、基本の EEUser インターフェースを Google 固有のフィールドで拡張します。

id:

string

Mastra ユーザー ID。Google の sub クレームを使用します。

googleId:

string

Google アカウントのサブジェクト識別子。

email?:

string

ユーザーのメールアドレス。

name?:

string

Google プロフィールのクレームから取得したユーザーの表示名。

avatarUrl?:

string

ユーザーの Google プロフィール画像の URL。

hostedDomain?:

string

検証済みの hd クレームから取得した Google Workspace ホストドメイン。

expiresAt?:

Date

検証済み ID トークンの有効期限（利用可能な場合）。

emailVerified?:

boolean

Google がメールアドレスを検証済みとして報告しているかどうか。

groups?:

string[]

事前に解決された任意の Google Workspace グループロール ID。

MastraRBACGoogle クラス

MastraRBACGoogle クラスは、Google Workspace グループを Mastra の権限にマッピングします。Google Admin SDK Directory API からユーザーグループを取得し、設定可能なロールマッピングと照合して解決します。MastraAuthGoogle またはその他の認証 Provider と組み合わせて使用します。

注記

RBAC には有効な Enterprise Edition ライセンスが必要です。開発環境ではライセンスなしで動作するためローカルで試すことができますが、本番環境ではライセンスが必要です。詳しくは、営業までお問い合わせください。

使用例

認証 Provider とともに MastraRBACGoogle を使用するには、rbac オプションに渡します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthGoogle, MastraRBACGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle(),
    rbac: new MastraRBACGoogle({
      serviceAccount: {
        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
      },
      roleMapping: {
        'admins@example.com': ['*'],
        'engineering@example.com': ['agents:*', 'workflows:*', 'tools:*'],
        'viewers@example.com': ['agents:read', 'workflows:read'],
        _default: [],
      },
    }),
  },
})

別の認証 Provider で Google Workspace RBAC を使用するには、その Provider のユーザーオブジェクトから Google Directory API のユーザーキーを解決する getUserKey 関数を渡します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
import { MastraRBACGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0(),
    rbac: new MastraRBACGoogle({
      getUserKey: user => user.email,
      serviceAccount: {
        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
      },
      roleMapping: {
        'engineering@example.com': ['agents:*', 'workflows:*'],
        'admins@example.com': ['*'],
        _default: [],
      },
    }),
  },
})

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

roleMapping:

RoleMapping

Google Workspace グループのロール ID を Mastra の権限文字列の配列にマッピングします。どのグループにも一致しないユーザーに権限を割り当てるには '_default' を使用します。'*'（フルアクセス）や 'agents:*'（Agent に対するすべての操作）などのワイルドカードをサポートします。

accessToken?:

string

事前に取得した Workspace Directory API アクセストークン。

getAccessToken?:

() => Promise<string> | string

Workspace Directory API アクセストークンを返すコールバック。

serviceAccount?:

GoogleWorkspaceServiceAccount

ドメイン全体の委任による Directory API アクセスに使用するサービスアカウントの認証情報。

GoogleWorkspaceServiceAccount

clientEmail:

string

Google サービスアカウントのメールアドレス。

privateKey:

string

PEM 形式でエンコードされた秘密鍵。.env ファイルのエスケープされた \n 値もサポートされます。

privateKeyId?:

string

任意の秘密鍵 ID。

subject?:

string

ドメイン全体の委任で偽装する Workspace 管理者ユーザー。

scopes?:

string[]

サービスアカウントトークンの OAuth スコープ。

getUserKey?:

(user: unknown) => string | undefined

認証済みユーザーから Directory API の userKey を抽出します。デフォルトは user.email です。

mapGroupToRoles?:

(group: GoogleWorkspaceGroup) => string[]

Google Workspace グループをロール ID にマッピングします。デフォルトは [group.email] です。

cache?:

PermissionCacheOptions

グループ検索用の LRU キャッシュを設定します。

PermissionCacheOptions

maxSize?:

number

キャッシュするユーザーの最大数。

ttlMs?:

number

有効期間（ミリ秒）。

RBAC メソッド

getRoles(user)

ユーザーの Google Workspace グループロール ID を返します。

const roles = await rbac.getRoles(user)

戻り値：Promise<string[]>

getPermissions(user)

Google Workspace グループと roleMapping から解決された Mastra の権限を返します。

const permissions = await rbac.getPermissions(user)

戻り値：Promise<string[]>

hasPermission(user, permission)

ユーザーが権限を持っているかどうかを確認します。

const canReadAgents = await rbac.hasPermission(user, 'agents:read')

戻り値：Promise<boolean>

hasRole(user, role)

ユーザーが特定の Google Workspace グループロールに解決されたかどうかを確認します。

const isAdmin = await rbac.hasRole(user, 'admins@example.com')

戻り値：Promise<boolean>

hasAllPermissions(user, permissions)

ユーザーが要求されたすべての権限を持っているかどうかを確認します。

const canManageAgents = await rbac.hasAllPermissions(user, ['agents:read', 'agents:update'])

戻り値：Promise<boolean>

hasAnyPermission(user, permissions)

ユーザーが要求された権限を少なくとも1つ持っているかどうかを確認します。

const canReadSomething = await rbac.hasAnyPermission(user, ['agents:read', 'workflows:read'])

戻り値：Promise<boolean>

getAvailableRoles()

roleMapping に設定されたロール ID を、_default を除いて返します。

const roles = await rbac.getAvailableRoles()

戻り値：Promise<{ id: string; name: string }[]>

getPermissionsForRole(roleId)

ロール ID に設定された権限を返します。

const permissions = await rbac.getPermissionsForRole('engineering@example.com')

戻り値：Promise<string[]>

clearCache()

キャッシュされたすべての Google Workspace グループ検索結果を消去します。

rbac.clearCache()

戻り値：void

clearUserCache(userKey)

メールアドレスなど、1つの Directory API ユーザーキーに対応するキャッシュ済みグループ検索結果を消去します。

rbac.clearUserCache('user@example.com')

戻り値：void

getCacheStats()

現在のグループ検索キャッシュのサイズと最大サイズを返します。

const stats = rbac.getCacheStats()

戻り値：{ size: number; maxSize: number }

追加設定

MastraRBACGoogle は GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=... を使用し、ページネーションを処理します。本番環境の Google Workspace デプロイではドメイン全体の委任が設定されたサービスアカウントを指定するか、アプリケーションがすでに Google API トークンを管理している場合は accessToken / getAccessToken を渡します。

user.groups がすでに配列である場合、MastraRBACGoogle はその値を使用し、Directory API を呼び出しません。空の groups 配列は、ユーザーに Google グループロールがないことを意味し、_default が設定されていれば、_default の権限に解決されます。

MastraRBACGoogle はサービスアカウントの環境変数を自動的には読み取りません。serviceAccount オプションを通じてサービスアカウントの認証情報を渡すか、accessToken / getAccessToken を渡します。

関連情報

Google 認証ドキュメント