MastraAuthGoogle and MastraRBACGoogle class

MastraAuthGoogle class

The MastraAuthGoogle class provides authentication for Mastra using Google Workspace. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies and verifies Google ID tokens. It integrates with the Mastra server through the auth option.

Usage example

src/mastra/index.ts

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'],
    }),
  },
})

备注

You can omit the constructor parameters if the required environment variables are set. In that case, use new MastraAuthGoogle() without any arguments.

Constructor parameters

clientId?:

string

= process.env.GOOGLE_CLIENT_ID

Google OAuth client ID.

clientSecret?:

string

= process.env.GOOGLE_CLIENT_SECRET

Google OAuth client secret. Required for Studio SSO.

redirectUri?:

string

= process.env.GOOGLE_REDIRECT_URI

OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Google Cloud OAuth client.

scopes?:

string[]

= ['openid', 'profile', 'email']

OAuth scopes requested during the login flow.

allowedDomains?:

string | string[]

= process.env.GOOGLE_ALLOWED_DOMAINS

Allowed Google Workspace hosted domains. Mastra validates these against the verified hd claim.

hostedDomain?:

string

= process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain

Hosted-domain login hint passed to Google as hd. This is a hint only and is not used for authorization.

session?:

GoogleSessionOptions

Session cookie configuration.

GoogleSessionOptions

cookieName?:

string

Name of the session cookie.

cookieMaxAge?:

number

Cookie max age in seconds.

cookiePassword?:

string

Password for encrypting session cookies. Must be at least 32 characters. If not set, an auto-generated value is used in development that does not survive restarts.

secureCookies?:

boolean

Set the Secure flag on session cookies.

name?:

string

= 'google'

Custom name for the auth provider instance.

Environment variables

The following environment variables are automatically used when constructor options aren't provided:

GOOGLE_CLIENT_ID:

string

Google OAuth client ID from your Google Cloud OAuth client.

GOOGLE_CLIENT_SECRET?:

string

Google OAuth client secret. Required for the SSO authorization code flow.

GOOGLE_REDIRECT_URI?:

string

OAuth redirect URI for the SSO callback.

GOOGLE_COOKIE_PASSWORD?:

string

Password for encrypting session cookies. Must be at least 32 characters.

GOOGLE_ALLOWED_DOMAINS?:

string

Comma-separated Google Workspace hosted domains to allow.

GOOGLE_HOSTED_DOMAIN?:

string

Hosted-domain login hint passed to Google during SSO login.

Authentication flow

MastraAuthGoogle authenticates requests in the following order:

1. Session cookie. With SSO enabled, the provider reads and decrypts the encrypted session cookie. A valid, unexpired session authenticates the user.
2. Google ID token fallback: If no valid session cookie is present, verifies the Authorization header token against Google's JWKS endpoint.

After authentication, authorizeUser checks that the user has a valid Google user ID, the token-derived expiration hasn't passed, and the user's verified hd claim matches allowedDomains when domains are configured.

Authentication methods

authenticateToken(token, request?)

Authenticates a Google ID token. When SSO is enabled, this method checks the encrypted session cookie before it verifies the Bearer token.

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

Returns: Promise<GoogleUser | null>

getCurrentUser(request)

Returns the authenticated user from a session cookie or Bearer Google ID token.

const user = await auth.getCurrentUser(request)

Returns: Promise<GoogleUser | null>

authorizeUser(user)

Returns true when the user has an ID, hasn't expired, and matches allowedDomains when domains are configured.

const allowed = auth.authorizeUser(user)

Returns: boolean

getUser(userId)

Returns null. Google ID tokens are verified directly, so this provider doesn't perform user lookup by ID.

const user = await auth.getUser(userId)

Returns: Promise<GoogleUser | null>

GoogleUser type

The GoogleUser type extends the base EEUser interface with Google-specific fields:

id:

string

Mastra user ID. Uses the Google sub claim.

googleId:

string

Google Account subject identifier.

email?:

string

User email address.

name?:

string

User display name from Google profile claims.

avatarUrl?:

string

URL to the user's Google profile picture.

hostedDomain?:

string

Google Workspace hosted domain from the verified hd claim.

expiresAt?:

Date

Verified ID token expiration time, when available.

emailVerified?:

boolean

Whether Google reports the email address as verified.

groups?:

string[]

Optional pre-resolved Google Workspace group role IDs.

MastraRBACGoogle class

The MastraRBACGoogle class maps Google Workspace groups to Mastra permissions. It fetches user groups from the Google Admin SDK Directory API and resolves them against a configurable role mapping. Use it with MastraAuthGoogle or any other auth provider.

备注

RBAC requires a valid Enterprise Edition license. It works without a license in development so you can try it locally, but you'll need a license for production. Contact sales for more information.

Usage example

Use MastraRBACGoogle alongside an auth provider by passing it to the rbac option:

src/mastra/index.ts

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: [],
      },
    }),
  },
})

To use Google Workspace RBAC with a different auth provider, pass a getUserKey function to resolve the Google Directory API user key from the other provider's user object:

src/mastra/index.ts

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: [],
      },
    }),
  },
})

Constructor parameters

roleMapping:

RoleMapping

Maps Google Workspace group role IDs to arrays of Mastra permission strings. Use '_default' to assign permissions to users who do not match any group. Supports wildcards like '*' (full access) and 'agents:*' (all agent actions).

accessToken?:

string

Pre-obtained Workspace Directory API access token.

getAccessToken?:

() => Promise<string> | string

Callback that returns a Workspace Directory API access token.

serviceAccount?:

GoogleWorkspaceServiceAccount

Service account credentials for domain-wide delegated Directory API access.

GoogleWorkspaceServiceAccount

clientEmail:

string

Google service account email.

privateKey:

string

PEM-encoded private key. Escaped \n values from .env files are supported.

privateKeyId?:

string

Optional private key ID.

subject?:

string

Workspace administrator user to impersonate with domain-wide delegation.

scopes?:

string[]

OAuth scopes for the service account token.

getUserKey?:

(user: unknown) => string | undefined

Extract the Directory API userKey from an authenticated user. Defaults to user.email.

mapGroupToRoles?:

(group: GoogleWorkspaceGroup) => string[]

Map a Google Workspace group to role IDs. Defaults to [group.email].

cache?:

PermissionCacheOptions

Configure the LRU cache for group lookups.

PermissionCacheOptions

maxSize?:

number

Maximum number of users to cache.

ttlMs?:

number

Time-to-live in milliseconds.

RBAC methods

getRoles(user)

Returns Google Workspace group role IDs for a user.

const roles = await rbac.getRoles(user)

Returns: Promise<string[]>

getPermissions(user)

Returns Mastra permissions resolved from Google Workspace groups and roleMapping.

const permissions = await rbac.getPermissions(user)

Returns: Promise<string[]>

hasPermission(user, permission)

Checks whether a user has a permission.

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

Returns: Promise<boolean>

hasRole(user, role)

Checks whether a user resolved to a specific Google Workspace group role.

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

Returns: Promise<boolean>

hasAllPermissions(user, permissions)

Checks whether a user has every requested permission.

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

Returns: Promise<boolean>

hasAnyPermission(user, permissions)

Checks whether a user has at least one requested permission.

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

Returns: Promise<boolean>

getAvailableRoles()

Returns the role IDs configured in roleMapping, excluding _default.

const roles = await rbac.getAvailableRoles()

Returns: Promise<{ id: string; name: string }[]>

getPermissionsForRole(roleId)

Returns the permissions configured for a role ID.

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

Returns: Promise<string[]>

clearCache()

Clears all cached Google Workspace group lookups.

rbac.clearCache()

Returns: void

clearUserCache(userKey)

Clears the cached group lookup for one Directory API user key, such as an email address.

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

Returns: void

getCacheStats()

Returns the current group lookup cache size and maximum size.

const stats = rbac.getCacheStats()

Returns: { size: number; maxSize: number }

Additional configuration

MastraRBACGoogle uses GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=... and handles pagination. Provide a service account with domain-wide delegation for production Google Workspace deployments, or pass accessToken / getAccessToken if your application already manages Google API tokens.

If user.groups is already an array, MastraRBACGoogle uses that value and doesn't call the Directory API. An empty groups array means the user has no Google group roles and resolves to _default permissions when _default is configured.

MastraRBACGoogle doesn't automatically read service-account environment variables. Pass service-account credentials through the serviceAccount option, or pass accessToken / getAccessToken.

Related

Google auth docs