MastraAuthGoogle 和 MastraRBACGoogle 类

MastraAuthGoogle 类

MastraAuthGoogle 类使用 Google Workspace 为 Mastra 提供身份验证。它实现使用加密 Session cookie 的 OAuth 2.0 / OIDC 登录流程，验证 Google ID token，并使用 auth 选项与 Mastra server 集成。

使用示例

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 client ID。

clientSecret?:

string

= process.env.GOOGLE_CLIENT_SECRET

Google OAuth client secret。Studio SSO 必需。

redirectUri?:

string

= process.env.GOOGLE_REDIRECT_URI

SSO callback 的 OAuth redirect URI。必须与 Google Cloud OAuth client 中配置的 redirect URI 一致。

scopes?:

string[]

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

登录流程中请求的 OAuth scope。

allowedDomains?:

string | string[]

= process.env.GOOGLE_ALLOWED_DOMAINS

允许的 Google Workspace 托管域。Mastra 会根据已验证的 hd claim 对其进行校验。

hostedDomain?:

string

= process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain

以 hd 形式传递给 Google 的托管域登录提示。该值仅用作提示，不用于授权。

session?:

GoogleSessionOptions

Session cookie 配置。

GoogleSessionOptions

cookieName?:

string

Session cookie 的名称。

cookieMaxAge?:

number

Cookie 的最大有效期，单位为秒。

cookiePassword?:

string

用于加密 Session cookie 的密码，长度必须至少为 32 个字符。如果未设置，开发环境会使用自动生成的值，该值在重启后不会保留。

secureCookies?:

boolean

为 Session cookie 设置 Secure 标志。

name?:

string

= 'google'

Auth Provider 实例的自定义名称。

环境变量

未提供构造函数选项时，会自动使用以下环境变量：

GOOGLE_CLIENT_ID:

string

来自 Google Cloud OAuth client 的 Google OAuth client ID。

GOOGLE_CLIENT_SECRET?:

string

Google OAuth client secret。SSO authorization code 流程必需。

GOOGLE_REDIRECT_URI?:

string

SSO callback 的 OAuth redirect URI。

GOOGLE_COOKIE_PASSWORD?:

string

用于加密 Session cookie 的密码，长度必须至少为 32 个字符。

GOOGLE_ALLOWED_DOMAINS?:

string

允许访问的 Google Workspace 托管域，以逗号分隔。

GOOGLE_HOSTED_DOMAIN?:

string

SSO 登录期间传递给 Google 的托管域登录提示。

身份验证流程

MastraAuthGoogle 按以下顺序对请求进行身份验证：

1. Session cookie。 启用 SSO 后，Provider 会读取并解密已加密的 Session cookie。有效且未过期的 Session 可完成用户身份验证。
2. Google ID token fallback：如果不存在有效的 Session cookie，则根据 Google 的 JWKS endpoint 验证 Authorization header 中的 token。

身份验证完成后，authorizeUser 会检查用户是否具有有效的 Google user ID、由 token 得出的过期时间是否尚未到期；如果配置了域，还会检查用户已验证的 hd claim 是否与 allowedDomains 匹配。

身份验证方法

authenticateToken(token, request?)

验证 Google ID token。启用 SSO 后，该方法会先检查加密的 Session cookie，再验证 Bearer token。

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

返回：Promise<GoogleUser | null>

getCurrentUser(request)

返回通过 Session cookie 或 Bearer Google ID token 验证的用户。

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 token 会被直接验证，因此该 Provider 不会按 ID 查找用户。

const user = await auth.getUser(userId)

返回：Promise<GoogleUser | null>

GoogleUser 类型

GoogleUser 类型扩展了基础 EEUser interface，并增加 Google 专用字段：

id:

string

Mastra user ID，使用 Google sub claim。

googleId:

string

Google Account subject 标识符。

email?:

string

用户电子邮件地址。

name?:

string

来自 Google profile claim 的用户显示名称。

avatarUrl?:

string

用户 Google 头像的 URL。

hostedDomain?:

string

来自已验证 hd claim 的 Google Workspace 托管域。

expiresAt?:

Date

已验证 ID token 的过期时间（如果可用）。

emailVerified?:

boolean

Google 是否将该电子邮件地址报告为已验证。

groups?:

string[]

可选的、预先解析的 Google Workspace group role ID。

MastraRBACGoogle 类

MastraRBACGoogle 类将 Google Workspace group 映射到 Mastra permission。它从 Google Admin SDK Directory API 获取用户 group，并根据可配置的 role mapping 进行解析。可以将其与 MastraAuthGoogle 或其他 Auth Provider 搭配使用。

备注

RBAC 需要有效的 Enterprise Edition license。在开发环境中无需 license 即可运行，方便本地试用；生产环境则需要 license。有关详细信息，请联系销售团队。

使用示例

将 MastraRBACGoogle 传给 rbac 选项，即可与 Auth Provider 搭配使用：

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: [],
      },
    }),
  },
})

如果要将 Google Workspace RBAC 与其他 Auth Provider 搭配使用，请传入 getUserKey 函数，从其他 Provider 的用户对象中解析 Google Directory API user key：

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 group role ID 映射到 Mastra permission 字符串数组。使用 '_default' 为不匹配任何 group 的用户分配 permission。支持 '*'（完全访问权限）和 'agents:*'（所有 Agent 操作）等通配符。

accessToken?:

string

预先获取的 Workspace Directory API access token。

getAccessToken?:

() => Promise<string> | string

返回 Workspace Directory API access token 的 callback。

serviceAccount?:

GoogleWorkspaceServiceAccount

用于在全域委派模式下访问 Directory API 的 service account 凭证。

GoogleWorkspaceServiceAccount

clientEmail:

string

Google service account 电子邮件地址。

privateKey:

string

PEM 编码的 private key。支持 .env 文件中转义的 \n 值。

privateKeyId?:

string

可选的 private key ID。

subject?:

string

通过全域委派模拟的 Workspace 管理员用户。

scopes?:

string[]

Service account token 的 OAuth scope。

getUserKey?:

(user: unknown) => string | undefined

从已验证用户中提取 Directory API userKey。默认为 user.email。

mapGroupToRoles?:

(group: GoogleWorkspaceGroup) => string[]

将 Google Workspace group 映射到 role ID。默认为 [group.email]。

cache?:

PermissionCacheOptions

配置用于 group 查找的 LRU cache。

PermissionCacheOptions

maxSize?:

number

可缓存的最大用户数。

ttlMs?:

number

有效期，单位为毫秒。

RBAC 方法

getRoles(user)

返回用户的 Google Workspace group role ID。

const roles = await rbac.getRoles(user)

返回：Promise<string[]>

getPermissions(user)

返回根据 Google Workspace group 和 roleMapping 解析的 Mastra permission。

const permissions = await rbac.getPermissions(user)

返回：Promise<string[]>

hasPermission(user, permission)

检查用户是否具有某项 permission。

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

返回：Promise<boolean>

hasRole(user, role)

检查用户是否已解析到指定的 Google Workspace group role。

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

返回：Promise<boolean>

hasAllPermissions(user, permissions)

检查用户是否具有请求的所有 permission。

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

返回：Promise<boolean>

hasAnyPermission(user, permissions)

检查用户是否至少具有一项请求的 permission。

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

返回：Promise<boolean>

getAvailableRoles()

返回 roleMapping 中配置的 role ID，不包括 _default。

const roles = await rbac.getAvailableRoles()

返回：Promise<{ id: string; name: string }[]>

getPermissionsForRole(roleId)

返回为某个 role ID 配置的 permission。

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

返回：Promise<string[]>

clearCache()

清除所有已缓存的 Google Workspace group 查找结果。

rbac.clearCache()

返回：void

clearUserCache(userKey)

清除一个 Directory API user key（例如电子邮件地址）的已缓存 group 查找结果。

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

返回：void

getCacheStats()

返回当前 group 查找 cache 的大小和最大容量。

const stats = rbac.getCacheStats()

返回：{ size: number; maxSize: number }

其他配置

MastraRBACGoogle 使用 GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=... 并处理分页。生产环境部署 Google Workspace 时，请提供具有全域委派能力的 service account；如果应用已自行管理 Google API token，也可以传入 accessToken / getAccessToken。

如果 user.groups 已经是数组，MastraRBACGoogle 会使用该值，而不会调用 Directory API。空的 groups 数组表示用户没有 Google group role；配置 _default 时，会解析为 _default permission。

MastraRBACGoogle 不会自动读取 service account 环境变量。请通过 serviceAccount 选项传入 service account 凭证，或传入 accessToken / getAccessToken。

相关内容

Google Auth 文档