> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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 :

```text
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**:

```bash
npm install @mastra/auth-google
```

**pnpm**:

```bash
pnpm add @mastra/auth-google
```

**Yarn**:

```bash
yarn add @mastra/auth-google
```

**Bun**:

```bash
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 :

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/reference/auth/google) 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 :

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/server/mastra-client) pour découvrir davantage d’options de configuration.

### Effectuer des requêtes authentifiées

**MastraClient**:

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

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

**cURL**:

```bash
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](https://mastra.zisheng.pro/fr/docs/server/auth)
- [Authentification composite](https://mastra.zisheng.pro/fr/docs/server/auth/composite-auth)
- [Référence de MastraAuthGoogle](https://mastra.zisheng.pro/fr/reference/auth/google)