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

# 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

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

> **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`): Identifiant client OAuth Google. (Default: `process.env.GOOGLE_CLIENT_ID`)

**clientSecret** (`string`): Secret client OAuth Google. Requis pour le SSO de Studio. (Default: `process.env.GOOGLE_CLIENT_SECRET`)

**redirectUri** (`string`): URI de redirection OAuth du callback SSO. Elle doit correspondre à l’URI de redirection configurée dans votre client OAuth Google Cloud. (Default: `process.env.GOOGLE_REDIRECT_URI`)

**scopes** (`string[]`): Scopes OAuth demandés pendant le flux de connexion. (Default: `['openid', 'profile', 'email']`)

**allowedDomains** (`string | string[]`): Domaines hébergés Google Workspace autorisés. Mastra les compare à la claim hd vérifiée. (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)

**hostedDomain** (`string`): 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. (Default: `process.env.GOOGLE_HOSTED_DOMAIN ou le seul domaine autorisé`)

**session** (`GoogleSessionOptions`): Configuration du cookie de session.

**session.cookieName** (`string`): Nom du cookie de session.

**session.cookieMaxAge** (`number`): Durée de vie maximale du cookie, en secondes.

**session.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.

**session.secureCookies** (`boolean`): Définit l’attribut Secure des cookies de session.

**name** (`string`): Nom personnalisé de l’instance du Provider d’authentification. (Default: `'google'`)

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

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

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

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

```typescript
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](https://mastra.ai/contact) pour en savoir plus.

### Exemple d’utilisation

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

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

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 :

```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 => 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.

**serviceAccount.clientEmail** (`string`): Adresse e-mail du compte de service Google.

**serviceAccount.privateKey** (`string`): Clé privée encodée au format PEM. Les valeurs \n échappées provenant de fichiers .env sont prises en charge.

**serviceAccount.privateKeyId** (`string`): Identifiant facultatif de la clé privée.

**serviceAccount.subject** (`string`): Utilisateur administrateur Workspace à représenter au moyen de la délégation à l’échelle du domaine.

**serviceAccount.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.

**cache.maxSize** (`number`): Nombre maximal d’utilisateurs à placer en cache.

**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.

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

```typescript
const permissions = await rbac.getPermissions(user)
```

Renvoie : `Promise<string[]>`

#### `hasPermission(user, permission)`

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

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

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

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

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

```typescript
const roles = await rbac.getAvailableRoles()
```

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

#### `getPermissionsForRole(roleId)`

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

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

Renvoie : `Promise<string[]>`

#### `clearCache()`

Efface du cache toutes les recherches de groupes Google Workspace.

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

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

Renvoie : `void`

#### `getCacheStats()`

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

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