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

# Classe MastraAuthWorkos

La classe `MastraAuthWorkos` fournit à Mastra une authentification fondée sur WorkOS. Elle vérifie les requêtes entrantes au moyen de tokens d’accès WorkOS et s’intègre au serveur Mastra à l’aide de l’option `auth`.

## Exemple d’utilisation

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
  },
})
```

> **Remarque:** Vous pouvez omettre les paramètres du constructeur si les variables d’environnement requises (`WORKOS_API_KEY` et `WORKOS_CLIENT_ID`) sont définies. Dans ce cas, utilisez `new MastraAuthWorkos()` sans aucun argument.

## Paramètres du constructeur

**apiKey** (`string`): Votre clé d’API WorkOS. Elle permet de s’authentifier auprès de l’API WorkOS pour vérifier les utilisateurs et gérer les organisations. (Default: `process.env.WORKOS_API_KEY`)

**clientId** (`string`): Votre ID client WorkOS. Il identifie votre application lors de l’échange de codes d’autorisation contre des tokens d’accès. (Default: `process.env.WORKOS_CLIENT_ID`)

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

**redirectUri** (`string`): URI de redirection OAuth utilisée par WorkOS AuthKit. Définissez-la lorsque vous utilisez le flux de connexion WorkOS intégré. (Default: `process.env.WORKOS_REDIRECT_URI`)

**fetchMemberships** (`boolean`): Charge les appartenances aux organisations pendant l’authentification. Définissez cette option sur true lorsque vous utilisez MastraFGAWorkos, afin que les vérifications FGA puissent résoudre l’ID d’appartenance à l’organisation approprié. (Default: `false`)

**trustJwtClaims** (`boolean`): Accorde suffisamment de confiance aux claims vérifiés du bearer token pour construire un WorkOSUser, même lorsque workos.userManagement.getUser() ne s’applique pas. Utilisez cette option pour les tokens de comptes de service ou machine à machine fondés sur un modèle JWT WorkOS personnalisé. (Default: `false`)

**jwtClaims** (`{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }`): Associe les claims JWT bearer vérifiés au WorkOSUser authentifié. Utile pour les modèles JWT personnalisés qui incluent organizationMembershipId ou d’autres claims propres à FGA.

## Variables d’environnement

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

**WORKOS\_API\_KEY** (`string`): Votre clé d’API WorkOS. Elle se trouve dans la section API Keys du WorkOS Dashboard.

**WORKOS\_CLIENT\_ID** (`string`): Votre ID client WorkOS. Il se trouve dans la section Applications du WorkOS Dashboard.

**WORKOS\_REDIRECT\_URI** (`string`): URI de redirection OAuth utilisée par WorkOS AuthKit lorsque vous employez le flux intégré fondé sur les sessions.

## Comportement d’autorisation par défaut

Par défaut, `MastraAuthWorkos` autorise tout utilisateur WorkOS authentifié dont l’objet utilisateur résolu contient à la fois `id` et `workosId`.

1. **Vérification du token** : le token d’accès est vérifié auprès de WorkOS afin de s’assurer qu’il est valide et n’a pas expiré
2. **Récupération de l’utilisateur** : les informations de l’utilisateur sont extraites du token vérifié
3. **Décision d’autorisation** : l’accès est accordé si l’utilisateur résolu contient les identifiants requis

Par défaut, `MastraAuthWorkos` agit comme un Provider d’authentification et non comme un filtre fondé sur les rôles.

## Chargement des appartenances pour FGA

Définissez `fetchMemberships: true` lorsque vous utilisez `MastraFGAWorkos`. Cette option charge les appartenances de l’utilisateur aux organisations WorkOS pendant l’authentification, afin que les vérifications FGA puissent résoudre l’ID d’appartenance à l’organisation approprié.

Lorsque `fetchMemberships` vaut `false`, Mastra omet l’appel WorkOS supplémentaire à `listOrganizationMemberships()` pour chaque requête authentifiée.

## Tokens de service et claims JWT

Si votre modèle JWT WorkOS inclut des claims personnalisés, vous pouvez les associer directement au `WorkOSUser` authentifié.

```typescript
import { MastraAuthWorkos } from '@mastra/auth-workos'

const auth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: process.env.WORKOS_REDIRECT_URI,
  trustJwtClaims: true,
  jwtClaims: {
    organizationId: 'org_id',
    organizationMembershipId: 'urn:mastra:organization_membership_id',
  },
})
```

Lorsque `trustJwtClaims` est activé, Mastra peut authentifier les bearer tokens vérifiés des principaux de service, même si `getUser()` n’est pas le chemin de recherche approprié. Il s’agit de la méthode recommandée pour transmettre des valeurs `organizationMembershipId` déjà résolues aux vérifications FGA dans les flux machine à machine.

## Autorisation personnalisée

Si vous avez besoin d’une autorisation plus stricte, créez une sous-classe de `MastraAuthWorkos` et remplacez `authorizeUser()` :

```typescript
import { MastraAuthWorkos } from '@mastra/auth-workos'
import type { HonoRequest } from 'hono'

class AdminOnlyWorkosAuth extends MastraAuthWorkos {
  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
    return user?.metadata?.role === 'admin'
  }
}
```

## Type d’utilisateur WorkOS

Le type `WorkOSUser` disponible dans `authorizeUser()` et dans les autres hooks d’authentification WorkOS comprend les champs utilisateur normalisés de Mastra, ainsi que des métadonnées propres à WorkOS. WorkOS permet également aux administrateurs de configurer des modèles JWT personnalisés ; la structure exacte peut donc varier selon votre configuration. L’exemple suivant illustre l’aspect possible d’un objet utilisateur fondé sur WorkOS :

```javascript
{
  'urn:myapp:full_name': 'John Doe',
  'urn:myapp:email': 'john.doe@example.com',
  'urn:myapp:organization_tier': 'bronze',
  'urn:myapp:user_language': 'en',
  'urn:myapp:organization_domain': 'example.com',
  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
  sub: 'user_01XYZ789ABC123DEF456GHI012',
  sid: 'session_01PQR456STU789VWX012YZA345',
  jti: '01MNO678PQR901STU234VWX567',
  org_id: 'org_01DEF234GHI567JKL890MNO123',
  role: 'member',
  roles: [ 'member' ],
  permissions: [],
  exp: 1758290589,
  iat: 1758290289
}
```

Les propriétés dotées du préfixe `urn:myapp:` sont des claims personnalisés configurés dans votre modèle JWT WorkOS. Les claims JWT standard comprennent `sub` (ID utilisateur), `iss` (émetteur), `exp` (expiration), ainsi que des claims propres à WorkOS tels que `org_id`, `role` et `roles`.

## Voir aussi

[Classe MastraAuthWorkos](https://mastra.zisheng.pro/fr/docs/server/auth/workos)