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

src/mastra/index.ts

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

= process.env.WORKOS_API_KEY

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.

clientId?:

string

= process.env.WORKOS_CLIENT_ID

Votre ID client WorkOS. Il identifie votre application lors de l’échange de codes d’autorisation contre des tokens d’accès.

name?:

string

= "workos"

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

redirectUri?:

string

= process.env.WORKOS_REDIRECT_URI

URI de redirection OAuth utilisée par WorkOS AuthKit. Définissez-la lorsque vous utilisez le flux de connexion WorkOS intégré.

fetchMemberships?:

boolean

= false

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

trustJwtClaims?:

boolean

= false

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

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

src/mastra/auth.ts

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() :

src/mastra/auth.ts

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 :

{
  '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