Classes MastraAuthGoogle et MastraRBACGoogle

Classe MastraAuthGoogle

La classe MastraAuthGoogle fournit à Mastra une authentification reposant sur Google Workspace. Elle met en œuvre un flux de connexion OAuth 2.0 / OIDC avec des cookies de session chiffrés, vérifie les jetons d’identité Google et s’intègre au serveur Mastra au moyen de l’option auth.

Exemple d’utilisation

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

remarque

Vous pouvez omettre les paramètres du constructeur si les variables d’environnement requises sont définies. Dans ce cas, utilisez new MastraAuthGoogle() sans argument.

Paramètres du constructeur

clientId?:

string

= process.env.GOOGLE_CLIENT_ID

Identifiant client OAuth Google.

clientSecret?:

string

= process.env.GOOGLE_CLIENT_SECRET

Secret client OAuth Google. Requis pour le SSO de Studio.

redirectUri?:

string

= process.env.GOOGLE_REDIRECT_URI

URI de redirection OAuth du callback SSO. Elle doit correspondre à l’URI de redirection configurée dans votre client OAuth Google Cloud.

scopes?:

string[]

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

Scopes OAuth demandés pendant le flux de connexion.

allowedDomains?:

string | string[]

= process.env.GOOGLE_ALLOWED_DOMAINS

Domaines hébergés Google Workspace autorisés. Mastra les compare à la claim hd vérifiée.

hostedDomain?:

string

= process.env.GOOGLE_HOSTED_DOMAIN ou le seul domaine autorisé

Indication de domaine hébergé transmise à Google sous la forme hd lors de la connexion. Il s’agit uniquement d’une indication, qui n’est pas utilisée pour l’autorisation.

session?:

GoogleSessionOptions

Configuration du cookie de session.

GoogleSessionOptions

cookieName?:

string

Nom du cookie de session.

cookieMaxAge?:

number

Durée de vie maximale du cookie, en secondes.

cookiePassword?:

string

Mot de passe utilisé pour chiffrer les cookies de session. Il doit comporter au moins 32 caractères. S’il n’est pas défini, une valeur générée automatiquement est utilisée en développement, mais elle n’est pas conservée après un redémarrage.

secureCookies?:

boolean

Définit l’attribut Secure des cookies de session.

name?:

string

= 'google'

Nom personnalisé de l’instance du Provider d’authentification.

Variables d’environnement

Les variables d’environnement suivantes sont utilisées automatiquement lorsque les options du constructeur ne sont pas fournies :

GOOGLE_CLIENT_ID:

string

Identifiant client OAuth Google provenant de votre client OAuth Google Cloud.

GOOGLE_CLIENT_SECRET?:

string

Secret client OAuth Google. Requis pour le flux SSO par code d’autorisation.

GOOGLE_REDIRECT_URI?:

string

URI de redirection OAuth du callback SSO.

GOOGLE_COOKIE_PASSWORD?:

string

Mot de passe utilisé pour chiffrer les cookies de session. Il doit comporter au moins 32 caractères.

GOOGLE_ALLOWED_DOMAINS?:

string

Domaines hébergés Google Workspace à autoriser, séparés par des virgules.

GOOGLE_HOSTED_DOMAIN?:

string

Indication de domaine hébergé transmise à Google pendant la connexion SSO.

Flux d’authentification

MastraAuthGoogle authentifie les requêtes dans l’ordre suivant :

1. Cookie de session. Lorsque le SSO est activé, le Provider lit et déchiffre le cookie de session chiffré. Une session valide et non expirée authentifie l’utilisateur.
2. Repli sur le jeton d’identité Google : si aucun cookie de session valide n’est présent, le jeton de l’en-tête Authorization est vérifié auprès de l’endpoint JWKS de Google.

Après l’authentification, authorizeUser vérifie que l’utilisateur possède un identifiant Google valide, que l’expiration issue du jeton n’est pas dépassée et, lorsque des domaines sont configurés, que la claim hd vérifiée de l’utilisateur correspond à allowedDomains.

Méthodes d’authentification

authenticateToken(token, request?)

Authentifie un jeton d’identité Google. Lorsque le SSO est activé, cette méthode vérifie le cookie de session chiffré avant de vérifier le jeton Bearer.

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

Renvoie : Promise<GoogleUser | null>

getCurrentUser(request)

Renvoie l’utilisateur authentifié à partir d’un cookie de session ou d’un jeton d’identité Google Bearer.

const user = await auth.getCurrentUser(request)

Renvoie : Promise<GoogleUser | null>

authorizeUser(user)

Renvoie true si l’utilisateur possède un identifiant, n’a pas expiré et, lorsque des domaines sont configurés, correspond à allowedDomains.

const allowed = auth.authorizeUser(user)

Renvoie : boolean

getUser(userId)

Renvoie null. Les jetons d’identité Google étant vérifiés directement, ce Provider ne recherche pas les utilisateurs par identifiant.

const user = await auth.getUser(userId)

Renvoie : Promise<GoogleUser | null>

Type GoogleUser

Le type GoogleUser étend l’interface de base EEUser avec des champs propres à Google :

id:

string

Identifiant utilisateur Mastra. Utilise la claim Google sub.

googleId:

string

Identifiant de sujet du compte Google.

email?:

string

Adresse e-mail de l’utilisateur.

name?:

string

Nom d’affichage de l’utilisateur issu des claims du profil Google.

avatarUrl?:

string

URL de la photo de profil Google de l’utilisateur.

hostedDomain?:

string

Domaine hébergé Google Workspace issu de la claim hd vérifiée.

expiresAt?:

Date

Date d’expiration vérifiée du jeton d’identité, lorsqu’elle est disponible.

emailVerified?:

boolean

Indique si Google considère l’adresse e-mail comme vérifiée.

groups?:

string[]

Identifiants de rôles de groupes Google Workspace facultatifs, résolus au préalable.

Classe MastraRBACGoogle

La classe MastraRBACGoogle associe les groupes Google Workspace aux permissions Mastra. Elle récupère les groupes d’un utilisateur dans l’API Directory du Google Admin SDK, puis les résout à l’aide d’un mappage de rôles configurable. Utilisez-la avec MastraAuthGoogle ou tout autre Provider d’authentification.

remarque

RBAC nécessite une licence Enterprise Edition valide. La fonctionnalité est utilisable sans licence en développement afin de pouvoir l’essayer localement, mais une licence est nécessaire en production. Contactez l’équipe commerciale pour en savoir plus.

Exemple d’utilisation

Utilisez MastraRBACGoogle avec un Provider d’authentification en le transmettant à l’option rbac :

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

Pour utiliser Google Workspace RBAC avec un autre Provider d’authentification, transmettez une fonction getUserKey qui détermine la clé utilisateur de l’API Google Directory à partir de l’objet utilisateur de l’autre Provider :

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

Paramètres du constructeur

roleMapping:

RoleMapping

Associe les identifiants de rôles de groupes Google Workspace à des tableaux de chaînes de permissions Mastra. Utilisez '_default' pour attribuer des permissions aux utilisateurs qui ne correspondent à aucun groupe. Prend en charge les caractères génériques tels que '*' (accès complet) et 'agents:*' (toutes les actions des Agents).

accessToken?:

string

Jeton d’accès à l’API Workspace Directory obtenu au préalable.

getAccessToken?:

() => Promise<string> | string

Fonction de rappel qui renvoie un jeton d’accès à l’API Workspace Directory.

serviceAccount?:

GoogleWorkspaceServiceAccount

Identifiants du compte de service pour un accès délégué à l’échelle du domaine à l’API Directory.

GoogleWorkspaceServiceAccount

clientEmail:

string

Adresse e-mail du compte de service Google.

privateKey:

string

Clé privée encodée au format PEM. Les valeurs \n échappées provenant de fichiers .env sont prises en charge.

privateKeyId?:

string

Identifiant facultatif de la clé privée.

subject?:

string

Utilisateur administrateur Workspace à représenter au moyen de la délégation à l’échelle du domaine.

scopes?:

string[]

Scopes OAuth du jeton du compte de service.

getUserKey?:

(user: unknown) => string | undefined

Extrait la valeur userKey de l’API Directory à partir d’un utilisateur authentifié. Valeur par défaut : user.email.

mapGroupToRoles?:

(group: GoogleWorkspaceGroup) => string[]

Associe un groupe Google Workspace à des identifiants de rôles. Valeur par défaut : [group.email].

cache?:

PermissionCacheOptions

Configure le cache LRU utilisé pour les recherches de groupes.

PermissionCacheOptions

maxSize?:

number

Nombre maximal d’utilisateurs à placer en cache.

ttlMs?:

number

Durée de vie, en millisecondes.

Méthodes RBAC

getRoles(user)

Renvoie les identifiants de rôles des groupes Google Workspace d’un utilisateur.

const roles = await rbac.getRoles(user)

Renvoie : Promise<string[]>

getPermissions(user)

Renvoie les permissions Mastra déterminées à partir des groupes Google Workspace et de roleMapping.

const permissions = await rbac.getPermissions(user)

Renvoie : Promise<string[]>

hasPermission(user, permission)

Vérifie si un utilisateur possède une permission.

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

Renvoie : Promise<boolean>

hasRole(user, role)

Vérifie si un rôle de groupe Google Workspace précis a été associé à l’utilisateur.

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

Renvoie : Promise<boolean>

hasAllPermissions(user, permissions)

Vérifie si un utilisateur possède toutes les permissions demandées.

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

Renvoie : Promise<boolean>

hasAnyPermission(user, permissions)

Vérifie si un utilisateur possède au moins l’une des permissions demandées.

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

Renvoie : Promise<boolean>

getAvailableRoles()

Renvoie les identifiants de rôles configurés dans roleMapping, à l’exclusion de _default.

const roles = await rbac.getAvailableRoles()

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

getPermissionsForRole(roleId)

Renvoie les permissions configurées pour un identifiant de rôle.

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

Renvoie : Promise<string[]>

clearCache()

Efface du cache toutes les recherches de groupes Google Workspace.

rbac.clearCache()

Renvoie : void

clearUserCache(userKey)

Efface du cache la recherche de groupes associée à une clé utilisateur de l’API Directory, par exemple une adresse e-mail.

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

Renvoie : void

getCacheStats()

Renvoie la taille actuelle et la taille maximale du cache des recherches de groupes.

const stats = rbac.getCacheStats()

Renvoie : { size: number; maxSize: number }

Configuration supplémentaire

MastraRBACGoogle utilise GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=... et gère la pagination. Pour les déploiements Google Workspace en production, fournissez un compte de service doté d’une délégation à l’échelle du domaine. Si votre application gère déjà les jetons de l’API Google, transmettez plutôt accessToken ou getAccessToken.

Si user.groups est déjà un tableau, MastraRBACGoogle utilise cette valeur et n’appelle pas l’API Directory. Un tableau groups vide signifie que l’utilisateur ne possède aucun rôle de groupe Google ; les permissions _default lui sont alors attribuées si _default est configuré.

MastraRBACGoogle ne lit pas automatiquement les variables d’environnement du compte de service. Transmettez les identifiants du compte de service au moyen de l’option serviceAccount, ou fournissez accessToken ou getAccessToken.

Voir aussi

Documentation de l’authentification Google