WorkOS

Le package @mastra/auth-workos fournit l'authentification WorkOS à Mastra. Il vérifie les requêtes entrantes à l'aide de jetons d'accès WorkOS et s'intègre au serveur Mastra grâce à l'option auth.

Prérequis

Cet exemple utilise l'authentification WorkOS. Veillez à :

1. créer un compte WorkOS sur workos.com ;
2. configurer une application dans votre tableau de bord WorkOS ;
3. configurer vos URI de redirection et les origines autorisées ;
4. configurer des organisations et les rôles des utilisateurs selon vos besoins.

.env

WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...

remarque

Vous trouverez votre clé API et votre ID client dans le tableau de bord WorkOS, respectivement sous « API Keys » et « Applications ».

Pour obtenir des instructions de configuration détaillées et adaptées à votre plateforme, consultez la documentation de WorkOS.

Installation

Avant d'utiliser la classe MastraAuthWorkos, vous devez installer le package @mastra/auth-workos.

npm

npm install @mastra/auth-workos@latest

pnpm

pnpm add @mastra/auth-workos@latest

Yarn

yarn add @mastra/auth-workos@latest

Bun

bun add @mastra/auth-workos@latest

Exemples d'utilisation

Utilisation de base avec des variables d'environnement

src/mastra/index.ts

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

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

Configuration personnalisée

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

Configuration

Autorisation par défaut

Par défaut, MastraAuthWorkos accorde l'accès à tout utilisateur WorkOS authentifié. La vérification de l'autorisation réussit lorsque l'objet utilisateur obtenu contient à la fois un ID utilisateur Mastra et un ID utilisateur WorkOS.

Chargement des appartenances pour FGA

Définissez fetchMemberships: true lorsque vous utilisez MastraFGAWorkos. Le Provider d'authentification charge alors les appartenances de l'utilisateur aux organisations WorkOS pendant l'authentification, afin que les vérifications FGA puissent déterminer l'ID d'appartenance à l'organisation approprié.

src/mastra/auth.ts

import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  fetchMemberships: true,
})

const workosFga = new MastraFGAWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

Lorsque fetchMemberships vaut false, Mastra n'effectue pas l'appel WorkOS supplémentaire à listOrganizationMemberships() pour chaque requête authentifiée.

Jetons de service et modèles JWT personnalisés

Pour les accès machine à machine ou via un compte de service, vous pouvez configurer MastraAuthWorkos afin qu'il approuve les claims vérifiés d'un jeton porteur issus d'un modèle JWT WorkOS personnalisé.

src/mastra/auth.ts

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

const workosAuth = 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',
  },
})

Cette option est utile lorsque votre modèle JWT contient déjà le contexte FGA précis dont Mastra a besoin, comme organizationMembershipId, des ID de locataire ou des identifiants de principal de service. Lorsque trustJwtClaims est activé, Mastra peut se rabattre sur ces claims vérifiés si un jeton porteur n'est pas destiné à effectuer un aller-retour via workos.userManagement.getUser().

Autorisation personnalisée

Si vous avez besoin d'une autorisation plus stricte, créez une sous-classe de MastraAuthWorkos et redéfinissez 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'
  }
}

const workosAuth = new AdminOnlyWorkosAuth({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

Consultez MastraAuthWorkos pour découvrir toutes les options de configuration disponibles.

Configuration côté client

Lorsque vous utilisez l'authentification WorkOS, vous devez implémenter le flux d'authentification WorkOS afin d'échanger un code d'autorisation contre un jeton d'accès, puis utiliser ce jeton dans vos requêtes Mastra.

Installer le SDK WorkOS

Commencez par installer le SDK WorkOS dans votre application :

npm

npm install @workos-inc/node

pnpm

pnpm add @workos-inc/node

Yarn

yarn add @workos-inc/node

Bun

bun add @workos-inc/node

Échanger le code contre un jeton d'accès

Une fois que les utilisateurs ont terminé le flux d'authentification WorkOS et sont revenus avec un code d'autorisation, échangez ce code contre un jeton d'accès :

lib/auth.ts

import { WorkOS } from '@workos-inc/node'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const authenticateWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  return authenticationResponse.accessToken
}

remarque

Consultez la documentation WorkOS User Management pour découvrir d'autres méthodes d'authentification et options de configuration.

Configurer MastraClient

Lorsque auth est activé, toutes les requêtes effectuées avec MastraClient doivent inclure un jeton d'accès WorkOS valide dans l'en-tête Authorization :

lib/mastra/mastra-client.ts

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

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'https://<mastra-api-url>',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}

info

Le jeton d'accès doit être précédé de Bearer dans l'en-tête Authorization.

Consultez le SDK client Mastra pour davantage d’options de configuration.

Effectuer des requêtes authentifiées

Une fois MastraClient configuré avec le jeton d'accès WorkOS, vous pouvez envoyer des requêtes authentifiées :

React

src/api/agents.ts

import { WorkOS } from '@workos-inc/node'
import { MastraClient } from '@mastra/client-js'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const callMastraWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  const token = authenticationResponse.accessToken

  const mastra = new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${token}`,
    },
  })

  const weatherAgent = mastra.getAgent('weatherAgent')
  const response = await weatherAgent.generate("What's the weather like in Nairobi")

  return response.text
}

cURL

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