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

# MastraAuthGoogle 與 MastraRBACGoogle 類別

## MastraAuthGoogle 類別

`MastraAuthGoogle` 類別使用 Google Workspace 為 Mastra 提供身分驗證。它會實作採用加密 session 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 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 flag。

**name** (`string`): 身分驗證 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 備援方式**：如果沒有有效的 session cookie，則會透過 Google 的 JWKS endpoint 驗證 `Authorization` header token。

身分驗證後，`authorizeUser` 會檢查使用者是否具有有效的 Google 使用者 ID、從 token 取得的到期時間是否尚未經過；如果已設定網域，還會檢查使用者已驗證的 `hd` claim 是否符合 `allowedDomains`。

### 身分驗證 method

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

驗證 Google ID token。啟用 SSO 時，此 method 會先檢查已加密的 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` 型別會以 Google 特定欄位擴充基礎 `EEUser` interface：

**id** (`string`): Mastra 使用者 ID。使用 Google sub claim。

**googleId** (`string`): Google Account subject 識別碼。

**email** (`string`): 使用者電子郵件地址。

**name** (`string`): 來自 Google 個人資料 claim 的使用者顯示名稱。

**avatarUrl** (`string`): 使用者 Google 個人資料圖片的 URL。

**hostedDomain** (`string`): 來自已驗證 hd claim 的 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 使用者 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 群組角色 ID 對應至 Mastra 權限字串的 array。使用 '\_default' 為不符合任何群組的使用者指派權限。支援 '\*'（完整存取權）和 'agents:\*'（所有 Agent 操作）等萬用字元。

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

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

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

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

**serviceAccount.privateKey** (`string`): 以 PEM 編碼的 private key。支援來自 .env 檔案且經逸出的 \n 值。

**serviceAccount.privateKeyId** (`string`): 選填的 private key ID。

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

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

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

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

**cache** (`PermissionCacheOptions`): 設定群組查詢的 LRU cache。

**cache.maxSize** (`number`): 可快取的使用者數量上限。

**cache.ttlMs** (`number`): 存留時間，以毫秒為單位。

### RBAC method

#### `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 使用者 key（例如電子郵件地址）的群組查詢快取。

```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` 已是 array，`MastraRBACGoogle` 會使用該值，且不會呼叫 Directory API。空的 `groups` array 表示使用者沒有 Google 群組角色；若已設定 `_default`，則會解析為 `_default` 權限。

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

## 相關內容

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