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

# MastraAuthGoogle 和 MastraRBACGoogle 類別

## MastraAuthGoogle 類別

`MastraAuthGoogle` 類別透過 Google Workspace 為 Mastra 提供身份驗證。它實作使用加密工作階段 Cookie 的 OAuth 2.0 / OIDC 登入流程、驗證 Google ID token，並透過 `auth` 選項與 Mastra 伺服器整合。

### 使用範例

```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 用戶端 ID。 (Default: `process.env.GOOGLE_CLIENT_ID`)

**clientSecret** (`string`): Google OAuth 用戶端密鑰。Studio SSO 必須提供此項。 (Default: `process.env.GOOGLE_CLIENT_SECRET`)

**redirectUri** (`string`): SSO 回呼的 OAuth 重新導向 URI。必須與 Google Cloud OAuth 用戶端中設定的重新導向 URI 相符。 (Default: `process.env.GOOGLE_REDIRECT_URI`)

**scopes** (`string[]`): 登入流程期間要求的 OAuth 範圍。 (Default: `['openid', 'profile', 'email']`)

**allowedDomains** (`string | string[]`): 允許的 Google Workspace 託管網域。Mastra 會根據已驗證的 hd 宣告來驗證這些網域。 (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)

**hostedDomain** (`string`): 以 hd 傳遞給 Google 的託管網域登入提示。這只是一項提示，不會用於授權。 (Default: `process.env.GOOGLE_HOSTED_DOMAIN 或唯一允許的網域`)

**session** (`GoogleSessionOptions`): 工作階段 Cookie 設定。

**session.cookieName** (`string`): 工作階段 Cookie 的名稱。

**session.cookieMaxAge** (`number`): Cookie 的最長有效期（秒）。

**session.cookiePassword** (`string`): 用於加密工作階段 Cookie 的密碼。必須至少有 32 個字元。如果未設定，開發環境會使用自動產生的值，而該值不會在重新啟動後保留。

**session.secureCookies** (`boolean`): 在工作階段 Cookie 上設定 Secure 標誌。

**name** (`string`): 身份驗證 Provider 實例的自訂名稱。 (Default: `'google'`)

### 環境變數

未提供建構函數選項時，系統會自動使用以下環境變數：

**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 token 後備方式**：如果沒有有效的工作階段 Cookie，便會透過 Google 的 JWKS 端點驗證 `Authorization` 標頭 token。

身份驗證後，`authorizeUser` 會檢查用戶是否有有效的 Google 用戶 ID、由 token 取得的到期時間是否尚未過去，以及在設定了網域時，用戶已驗證的 `hd` 宣告是否與 `allowedDomains` 相符。

### 身份驗證方法

#### `authenticateToken(token, request?)`

驗證 Google ID token。啟用 SSO 後，此方法會先檢查已加密的工作階段 Cookie，然後才驗證 Bearer token。

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

傳回：`Promise<GoogleUser | null>`

#### `getCurrentUser(request)`

從工作階段 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` 類型以 Google 專用欄位擴充基礎 `EEUser` 介面：

**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 token 的到期時間（如有）。

**emailVerified** (`boolean`): Google 是否回報該電郵地址已經驗證。

**groups** (`string[]`): 選填的預先解析 Google Workspace 群組角色 ID。

## MastraRBACGoogle 類別

`MastraRBACGoogle` 類別會將 Google Workspace 群組對應至 Mastra 權限。它從 Google Admin SDK Directory API 擷取用戶群組，並根據可設定的角色對應解析這些群組。你可以將它與 `MastraAuthGoogle` 或任何其他身份驗證 Provider 配合使用。

> **備註:** RBAC 需要有效的 Enterprise Edition 授權。在開發環境中，即使沒有授權也可運作，讓你在本機試用；但正式環境需要授權。如需更多資料，請[聯絡銷售團隊](https://mastra.ai/contact)。

### 使用範例

將 `MastraRBACGoogle` 傳遞至 `rbac` 選項，便可與身份驗證 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 與其他身份驗證 Provider 配合使用，請傳入 `getUserKey` 函數，從另一個 Provider 的用戶物件解析 Google Directory API 用戶鍵：

```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 群組角色 ID 對應至 Mastra 權限字串陣列。使用 '\_default' 向不符合任何群組的用戶指派權限。支援 '\*'（完整存取權）和 'agents:\*'（所有 Agent 操作）等萬用字元。

**accessToken** (`string`): 預先取得的 Workspace Directory API 存取 token。

**getAccessToken** (`() => Promise<string> | string`): 傳回 Workspace Directory API 存取 token 的回呼。

**serviceAccount** (`GoogleWorkspaceServiceAccount`): 用於全網域委派 Directory API 存取的服務帳戶憑證。

**serviceAccount.clientEmail** (`string`): Google 服務帳戶電郵。

**serviceAccount.privateKey** (`string`): 以 PEM 編碼的私密金鑰。支援來自 .env 檔案的逸出 \n 值。

**serviceAccount.privateKeyId** (`string`): 選填的私密金鑰 ID。

**serviceAccount.subject** (`string`): 使用全網域委派模擬的 Workspace 管理員用戶。

**serviceAccount.scopes** (`string[]`): 服務帳戶 token 的 OAuth 範圍。

**getUserKey** (`(user: unknown) => string | undefined`): 從已驗證身份的用戶擷取 Directory API userKey。預設為 user.email。

**mapGroupToRoles** (`(group: GoogleWorkspaceGroup) => string[]`): 將 Google Workspace 群組對應至角色 ID。預設為 \[group.email]。

**cache** (`PermissionCacheOptions`): 設定用於群組查找的 LRU 快取。

**cache.maxSize** (`number`): 可快取的用戶數目上限。

**cache.ttlMs** (`number`): 存留時間（毫秒）。

### RBAC 方法

#### `getRoles(user)`

傳回用戶的 Google Workspace 群組角色 ID。

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

傳回：`Promise<string[]>`

#### `getPermissions(user)`

傳回從 Google Workspace 群組和 `roleMapping` 解析的 Mastra 權限。

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

傳回：`Promise<string[]>`

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

檢查用戶是否擁有某項權限。

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

傳回：`Promise<boolean>`

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

檢查用戶是否解析至特定 Google Workspace 群組角色。

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

傳回：`Promise<boolean>`

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

檢查用戶是否擁有要求的所有權限。

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

傳回：`Promise<boolean>`

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

檢查用戶是否擁有至少一項要求的權限。

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

傳回：`Promise<boolean>`

#### `getAvailableRoles()`

傳回 `roleMapping` 中設定的角色 ID，但不包括 `_default`。

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

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

#### `getPermissionsForRole(roleId)`

傳回為角色 ID 設定的權限。

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

傳回：`Promise<string[]>`

#### `clearCache()`

清除所有已快取的 Google Workspace 群組查找結果。

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

傳回：`void`

#### `clearUserCache(userKey)`

清除一個 Directory API 用戶鍵（例如電郵地址）的已快取群組查找結果。

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

傳回：`void`

#### `getCacheStats()`

傳回目前群組查找快取的大小和大小上限。

```typescript
const stats = rbac.getCacheStats()
```

傳回：`{ size: number; maxSize: number }`

### 其他設定

`MastraRBACGoogle` 使用 `GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=...` 並處理分頁。正式 Google Workspace 部署應提供具備全網域委派的服務帳戶；如果你的應用程式已管理 Google API token，也可以傳入 `accessToken` / `getAccessToken`。

如果 `user.groups` 已經是陣列，`MastraRBACGoogle` 會使用該值，而不會呼叫 Directory API。空的 `groups` 陣列表示用戶沒有 Google 群組角色；設定了 `_default` 時，系統會解析至 `_default` 權限。

`MastraRBACGoogle` 不會自動讀取服務帳戶環境變數。請透過 `serviceAccount` 選項傳入服務帳戶憑證，或傳入 `accessToken` / `getAccessToken`。

## 相關內容

[Google 身份驗證文件](https://mastra.zisheng.pro/zh-HK/docs/server/auth/google)