MastraAuthGoogle 與 MastraRBACGoogle 類別
MastraAuthGoogle 類別「MastraAuthGoogle 類別」的直接連結
MastraAuthGoogle 類別使用 Google Workspace 為 Mastra 提供身分驗證。它會實作採用加密 session 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 claim 比對。hostedDomain?:
hd 傳遞給 Google 的代管網域登入提示。此值僅供提示，不會用於授權。session?:
cookieName?:
cookieMaxAge?:
cookiePassword?:
secureCookies?:
Secure flag。name?:
環境變數「環境變數」的直接連結
未提供建構函式選項時，會自動使用以下環境變數：
GOOGLE_CLIENT_ID:
GOOGLE_CLIENT_SECRET?:
GOOGLE_REDIRECT_URI?:
GOOGLE_COOKIE_PASSWORD?:
GOOGLE_ALLOWED_DOMAINS?:
GOOGLE_HOSTED_DOMAIN?:
身分驗證流程「身分驗證流程」的直接連結
MastraAuthGoogle 會依下列順序驗證要求：
- Session cookie。 啟用 SSO 時，Provider 會讀取並解密已加密的 session cookie。有效且未過期的 session 可驗證使用者身分。
- Google ID token 備援方式：如果沒有有效的 session cookie，則會透過 Google 的 JWKS endpoint 驗證
Authorizationheader token。
身分驗證後，authorizeUser 會檢查使用者是否具有有效的 Google 使用者 ID、從 token 取得的到期時間是否尚未經過；如果已設定網域，還會檢查使用者已驗證的 hd claim 是否符合 allowedDomains。
身分驗證 method「身分驗證 method」的直接連結
authenticateToken(token, request?)「authenticatetokentoken-request」的直接連結
驗證 Google ID token。啟用 SSO 時，此 method 會先檢查已加密的 session cookie，再驗證 Bearer token。
const user = await auth.authenticateToken(idToken, request)
傳回：Promise<GoogleUser | null>
getCurrentUser(request)「getcurrentuserrequest」的直接連結
從 session 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 interface：
id:
sub claim。googleId:
email?:
name?:
avatarUrl?:
hostedDomain?:
hd claim 的 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 使用者 key：
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 method「RBAC method」的直接連結
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 使用者 key（例如電子郵件地址）的群組查詢快取。
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 已是 array，MastraRBACGoogle 會使用該值，且不會呼叫 Directory API。空的 groups array 表示使用者沒有 Google 群組角色；若已設定 _default，則會解析為 _default 權限。
MastraRBACGoogle 不會自動讀取服務帳戶環境變數。請透過 serviceAccount 選項傳入服務帳戶認證資訊，或傳入 accessToken / getAccessToken。