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

# MastraAuthGoogle 和 MastraRBACGoogle 类

## MastraAuthGoogle 类

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

### 使用示例

```typescript
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`): Google OAuth client ID。 (Default: `process.env.GOOGLE_CLIENT_ID`)

**clientSecret** (`string`): Google OAuth client secret。Studio SSO 必需。 (Default: `process.env.GOOGLE_CLIENT_SECRET`)

**redirectUri** (`string`): SSO callback 的 OAuth redirect URI。必须与 Google Cloud OAuth client 中配置的 redirect URI 一致。 (Default: `process.env.GOOGLE_REDIRECT_URI`)

**scopes** (`string[]`): 登录流程中请求的 OAuth scope。 (Default: `['openid', 'profile', 'email']`)

**allowedDomains** (`string | string[]`): 允许的 Google Workspace 托管域。Mastra 会根据已验证的 hd claim 对其进行校验。 (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)

**hostedDomain** (`string`): 以 hd 形式传递给 Google 的托管域登录提示。该值仅用作提示，不用于授权。 (Default: `process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain`)

**session** (`GoogleSessionOptions`): Session cookie 配置。

**session.cookieName** (`string`): Session cookie 的名称。

**session.cookieMaxAge** (`number`): Cookie 的最大有效期，单位为秒。

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

**session.secureCookies** (`boolean`): 为 Session cookie 设置 Secure 标志。

**name** (`string`): Auth Provider 实例的自定义名称。 (Default: `'google'`)

### 环境变量

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

**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。

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

返回：`Promise<GoogleUser | null>`

#### `getCurrentUser(request)`

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

```typescript
const user = await auth.getCurrentUser(request)
```

返回：`Promise<GoogleUser | null>`

#### `authorizeUser(user)`

当用户具有 ID、尚未过期，并且在配置域时与 `allowedDomains` 匹配，则返回 `true`。

```typescript
const allowed = auth.authorizeUser(user)
```

返回：`boolean`

#### `getUser(userId)`

返回 `null`。Google ID token 会被直接验证，因此该 Provider 不会按 ID 查找用户。

```typescript
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。有关详细信息，请[联系销售团队](https://mastra.ai/contact)。

### 使用示例

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

```typescript
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：

```typescript
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 凭证。

**serviceAccount.clientEmail** (`string`): Google service account 电子邮件地址。

**serviceAccount.privateKey** (`string`): PEM 编码的 private key。支持 .env 文件中转义的 \n 值。

**serviceAccount.privateKeyId** (`string`): 可选的 private key ID。

**serviceAccount.subject** (`string`): 通过全域委派模拟的 Workspace 管理员用户。

**serviceAccount.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。

**cache.maxSize** (`number`): 可缓存的最大用户数。

**cache.ttlMs** (`number`): 有效期，单位为毫秒。

### RBAC 方法

#### `getRoles(user)`

返回用户的 Google Workspace group role ID。

```typescript
const roles = await rbac.getRoles(user)
```

返回：`Promise<string[]>`

#### `getPermissions(user)`

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

```typescript
const permissions = await rbac.getPermissions(user)
```

返回：`Promise<string[]>`

#### `hasPermission(user, permission)`

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

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

返回：`Promise<boolean>`

#### `hasRole(user, role)`

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

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

返回：`Promise<boolean>`

#### `hasAllPermissions(user, permissions)`

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

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

返回：`Promise<boolean>`

#### `hasAnyPermission(user, permissions)`

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

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

返回：`Promise<boolean>`

#### `getAvailableRoles()`

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

```typescript
const roles = await rbac.getAvailableRoles()
```

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

#### `getPermissionsForRole(roleId)`

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

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

返回：`Promise<string[]>`

#### `clearCache()`

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

```typescript
rbac.clearCache()
```

返回：`void`

#### `clearUserCache(userKey)`

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

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

返回：`void`

#### `getCacheStats()`

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

```typescript
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 文档](https://mastra.zisheng.pro/docs/server/auth/google)