Google

Le package @mastra/auth-google fournit à Mastra une authentification et un contrôle d’accès fondé sur les rôles au moyen de Google Workspace. Il prend en charge un flux de connexion OAuth 2.0 / OIDC avec des cookies de session chiffrés, vérifie les tokens d’identification Google et associe les groupes Google Workspace aux autorisations Mastra.

Utilisez-le lorsque les utilisateurs de Studio se connectent avec Google et que l’accès doit être limité à un ou plusieurs domaines Google Workspace.

Prérequis

Ce guide utilise l’authentification Google Workspace. Veillez à :

1. Créer ou sélectionner un projet Google Cloud
2. Configurer un client OAuth pour les applications web
3. Ajouter l’URL de callback SSO de Mastra aux URI de redirection autorisés
4. Configurer les groupes Google Workspace si vous prévoyez d’utiliser le RBAC

Pour utiliser le RBAC de Google Groups, configurez également un compte de service Google Workspace avec délégation à l’échelle du domaine et accordez-lui le scope de lecture seule des groupes dans Directory API :

https://www.googleapis.com/auth/admin.directory.group.readonly

Vérifiez que vos variables d’environnement sont définies.

.env

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:4111/api/auth/sso/callback
GOOGLE_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
GOOGLE_ALLOWED_DOMAINS=example.com

GOOGLE_SERVICE_ACCOUNT_EMAIL=service-account@project.iam.gserviceaccount.com
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
GOOGLE_WORKSPACE_ADMIN_EMAIL=admin@example.com

remarque

GOOGLE_COOKIE_PASSWORD chiffre les cookies de session. Si cette variable est omise, une valeur générée automatiquement est utilisée, mais elle ne survit pas aux redémarrages du serveur. Définissez-la explicitement en production.

MastraAuthGoogle lit automatiquement les variables d’authentification GOOGLE_*. Les variables du compte de service présentées ci-dessus sont lues par le code de configuration que vous transmettez à MastraRBACGoogle.

Installation

Avant de pouvoir utiliser la classe MastraAuthGoogle, installez le package @mastra/auth-google.

npm

npm install @mastra/auth-google

pnpm

pnpm add @mastra/auth-google

Yarn

yarn add @mastra/auth-google

Bun

bun add @mastra/auth-google

Exemples d’utilisation

Utilisation de base avec les variables d’environnement

Lorsque les variables d’environnement ci-dessus sont définies, tous les paramètres du constructeur sont facultatifs :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle(),
  },
})

attention

Utilisez allowedDomains ou GOOGLE_ALLOWED_DOMAINS pour imposer l’accès à Workspace. Mastra vérifie le claim hd validé par Google, et non le suffixe de l’adresse e-mail.

Configuration personnalisée

Transmettez directement les options du constructeur si vous ne souhaitez pas dépendre des variables d’environnement :

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

Authentification avec le RBAC de Google Groups

Ajoutez MastraRBACGoogle pour associer les groupes Google Workspace aux autorisations Mastra :

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: [], // users with unmapped groups get no permissions
      },
    }),
  },
})

Utilisation avec plusieurs fournisseurs

Utilisez un autre fournisseur d’authentification, comme Auth0 ou Clerk, pour la connexion et les groupes Google Workspace pour le RBAC. Transmettez une fonction getUserKey afin de résoudre la clé utilisateur de Google Directory API à partir de l’objet utilisateur de l’autre fournisseur :

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 => {
        if (!user || typeof user !== 'object') return undefined

        const { email } = user as { email?: unknown }
        return typeof email === 'string' ? email : undefined
      },
      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: [],
      },
    }),
  },
})

Consultez la référence de MastraAuthGoogle pour découvrir toutes les options de configuration disponibles.

Mappage des rôles

L’option roleMapping associe les adresses e-mail des groupes Google Workspace à des tableaux de chaînes d’autorisations Mastra. Les autorisations suivent un modèle resource:action et prennent en charge les caractères génériques :

const rbac = new MastraRBACGoogle({
  roleMapping: {
    // full access to everything
    'admins@example.com': ['*'],

    // full access to agents and workflows
    'engineering@example.com': ['agents:*', 'workflows:*'],

    // read-only access
    'viewers@example.com': ['agents:read', 'workflows:read'],

    // users whose groups don't match any key above
    _default: [],
  },
})

Les adresses e-mail des groupes servent par défaut d’identifiants de rôle. Utilisez mapGroupToRoles si vous souhaitez effectuer le mappage à partir du nom du groupe ou d’une autre propriété. La clé _default attribue des autorisations aux utilisateurs dont les groupes Google Workspace ne correspondent à aucune autre clé.

Configuration côté client

Lorsque l’authentification est activée, les requêtes vers les routes Mastra nécessitent une authentification. Lorsque le SSO est activé avec GOOGLE_CLIENT_SECRET, MastraAuthGoogle utilise la connexion Google et définit un cookie de session chiffré après la connexion.

Session par cookie (recommandé)

Pour les requêtes inter-origines, par exemple lorsqu’un frontend sur :3000 appelle Mastra sur :4111, activez les identifiants CORS sur le serveur Mastra :

src/mastra/index.ts

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle(),
    cors: {
      origin: 'http://localhost:3000',
      credentials: true,
    },
  },
})

Configurez le client afin qu’il inclue les identifiants :

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})

Token Bearer

Vous pouvez également transmettre un token d’identification Google comme token Bearer. Mastra vérifie le token auprès de l’endpoint JSON Web Key Set (JWKS) de Google :

lib/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const createMastraClient = (idToken: string) => {
  return new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${idToken}`,
    },
  })
}

Consultez la page SDK client Mastra pour découvrir davantage d’options de configuration.

Effectuer des requêtes authentifiées

MastraClient

src/api/agents.ts

import { mastraClient } from '../lib/mastra-client'

const agent = mastraClient.getAgent('weatherAgent')
const response = await agent.generate('Weather in London')
console.log(response)

cURL

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-google-id-token>" \
  -d '{
    "messages": "Weather in London"
  }'

Résolution des problèmes

• Erreur 401 après la connexion : vérifiez que GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET et GOOGLE_REDIRECT_URI correspondent au client OAuth Google Cloud.
• Les utilisateurs de Workspace sont refusés : vérifiez que GOOGLE_ALLOWED_DOMAINS correspond au claim hd du token d’identification Google.
• Les comptes Gmail grand public sont refusés : ce comportement est attendu lorsque allowedDomains est configuré, car les comptes Gmail ne possèdent pas de claim hd Workspace.
• Le RBAC renvoie les autorisations par défaut : aucun rôle n’a été résolu pour l’utilisateur. Vérifiez l’adresse e-mail de l’utilisateur ou la fonction getUserKey personnalisée, l’appartenance aux groupes Google et roleMapping. Si la recherche dans Directory API échoue, le fournisseur lève une erreur au lieu de renvoyer _default.
• Les cookies ne sont pas envoyés entre les origines : définissez credentials: "include" dans MastraClient et configurez server.cors avec l’origine de votre frontend et credentials: true.
• La session est perdue après un redémarrage : définissez GOOGLE_COOKIE_PASSWORD sur une valeur stable d’au moins 32 caractères. Sans cette variable, une clé générée automatiquement est utilisée en développement et change à chaque redémarrage.

Ressources associées

• Vue d’ensemble de l’authentification
• Authentification composite
• Référence de MastraAuthGoogle