MastraAuthGoogle 和 MastraRBACGoogle 類別
MastraAuthGoogle 類別MastraAuthGoogle 類別 的直接連結
MastraAuthGoogle 類別透過 Google Workspace 為 Mastra 提供身份驗證。它實作使用加密工作階段 Cookie 的 OAuth 2.0 / OIDC 登入流程、驗證 Google ID token，並透過 auth 選項與 Mastra 伺服器整合。
使用範例使用範例 的直接連結
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?:
clientSecret?:
redirectUri?:
scopes?:
allowedDomains?:
hd 宣告來驗證這些網域。hostedDomain?:
hd 傳遞給 Google 的託管網域登入提示。這只是一項提示，不會用於授權。session?:
cookieName?:
cookieMaxAge?:
cookiePassword?:
secureCookies?:
Secure 標誌。name?:
環境變數環境變數 的直接連結
未提供建構函數選項時，系統會自動使用以下環境變數：
GOOGLE_CLIENT_ID:
GOOGLE_CLIENT_SECRET?:
GOOGLE_REDIRECT_URI?:
GOOGLE_COOKIE_PASSWORD?:
GOOGLE_ALLOWED_DOMAINS?:
GOOGLE_HOSTED_DOMAIN?:
身份驗證流程身份驗證流程 的直接連結
MastraAuthGoogle 按以下次序驗證要求：
- 工作階段 Cookie。 啟用 SSO 後，Provider 會讀取並解密已加密的工作階段 Cookie。有效且未過期的工作階段可驗證用戶身份。
- Google ID token 後備方式：如果沒有有效的工作階段 Cookie，便會透過 Google 的 JWKS 端點驗證
Authorization標頭 token。
身份驗證後，authorizeUser 會檢查用戶是否有有效的 Google 用戶 ID、由 token 取得的到期時間是否尚未過去，以及在設定了網域時，用戶已驗證的 hd 宣告是否與 allowedDomains 相符。
身份驗證方法身份驗證方法 的直接連結
authenticateToken(token, request?)authenticatetokentoken-request 的直接連結
驗證 Google ID token。啟用 SSO 後，此方法會先檢查已加密的工作階段 Cookie，然後才驗證 Bearer token。
const user = await auth.authenticateToken(idToken, request)
傳回：Promise<GoogleUser | null>
getCurrentUser(request)getcurrentuserrequest 的直接連結
從工作階段 Cookie 或 Bearer Google ID token 傳回已驗證身份的用戶。
const user = await auth.getCurrentUser(request)
傳回：Promise<GoogleUser | null>
authorizeUser(user)authorizeuseruser 的直接連結
當用戶有 ID、尚未過期，並且在設定了網域時與 allowedDomains 相符，便傳回 true。
const allowed = auth.authorizeUser(user)
傳回：boolean
getUser(userId)getuseruserid 的直接連結
傳回 null。Google ID token 會直接驗證，因此此 Provider 不會按 ID 查找用戶。
const user = await auth.getUser(userId)
傳回：Promise<GoogleUser | null>
GoogleUser 類型googleuser-type 的直接連結
GoogleUser 類型以 Google 專用欄位擴充基礎 EEUser 介面：
id:
sub 宣告。googleId:
email?:
name?:
avatarUrl?:
hostedDomain?:
hd 宣告的 Google Workspace 託管網域。expiresAt?:
emailVerified?:
groups?:
MastraRBACGoogle 類別MastraRBACGoogle 類別 的直接連結
MastraRBACGoogle 類別會將 Google Workspace 群組對應至 Mastra 權限。它從 Google Admin SDK Directory API 擷取用戶群組，並根據可設定的角色對應解析這些群組。你可以將它與 MastraAuthGoogle 或任何其他身份驗證 Provider 配合使用。
RBAC 需要有效的 Enterprise Edition 授權。在開發環境中，即使沒有授權也可運作，讓你在本機試用；但正式環境需要授權。如需更多資料，請聯絡銷售團隊。
使用範例使用範例 的直接連結
將 MastraRBACGoogle 傳遞至 rbac 選項，便可與身份驗證 Provider 配合使用：
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 用戶鍵：
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:
'_default' 向不符合任何群組的用戶指派權限。支援 '*'（完整存取權）和 'agents:*'（所有 Agent 操作）等萬用字元。accessToken?:
getAccessToken?:
serviceAccount?:
clientEmail:
privateKey:
\n 值。privateKeyId?:
subject?:
scopes?:
getUserKey?:
userKey。預設為 user.email。mapGroupToRoles?:
[group.email]。cache?:
maxSize?:
ttlMs?:
RBAC 方法RBAC 方法 的直接連結
getRoles(user)getrolesuser 的直接連結
傳回用戶的 Google Workspace 群組角色 ID。
const roles = await rbac.getRoles(user)
傳回：Promise<string[]>
getPermissions(user)getpermissionsuser 的直接連結
傳回從 Google Workspace 群組和 roleMapping 解析的 Mastra 權限。
const permissions = await rbac.getPermissions(user)
傳回：Promise<string[]>
hasPermission(user, permission)haspermissionuser-permission 的直接連結
檢查用戶是否擁有某項權限。
const canReadAgents = await rbac.hasPermission(user, 'agents:read')
傳回：Promise<boolean>
hasRole(user, role)hasroleuser-role 的直接連結
檢查用戶是否解析至特定 Google Workspace 群組角色。
const isAdmin = await rbac.hasRole(user, 'admins@example.com')
傳回：Promise<boolean>
hasAllPermissions(user, permissions)hasallpermissionsuser-permissions 的直接連結
檢查用戶是否擁有要求的所有權限。
const canManageAgents = await rbac.hasAllPermissions(user, ['agents:read', 'agents:update'])
傳回：Promise<boolean>
hasAnyPermission(user, permissions)hasanypermissionuser-permissions 的直接連結
檢查用戶是否擁有至少一項要求的權限。
const canReadSomething = await rbac.hasAnyPermission(user, ['agents:read', 'workflows:read'])
傳回：Promise<boolean>
getAvailableRoles()getavailableroles 的直接連結
傳回 roleMapping 中設定的角色 ID，但不包括 _default。
const roles = await rbac.getAvailableRoles()
傳回：Promise<{ id: string; name: string }[]>
getPermissionsForRole(roleId)getpermissionsforroleroleid 的直接連結
傳回為角色 ID 設定的權限。
const permissions = await rbac.getPermissionsForRole('engineering@example.com')
傳回：Promise<string[]>
clearCache()clearcache 的直接連結
清除所有已快取的 Google Workspace 群組查找結果。
rbac.clearCache()
傳回：void
clearUserCache(userKey)clearusercacheuserkey 的直接連結
清除一個 Directory API 用戶鍵（例如電郵地址）的已快取群組查找結果。
rbac.clearUserCache('user@example.com')
傳回：void
getCacheStats()getcachestats 的直接連結
傳回目前群組查找快取的大小和大小上限。
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。