Workers

Lorsque les Workers s’exécutent dans des processus distincts de l’API, ils communiquent via HTTP. Le Worker d’orchestration appelle le point de terminaison d’exécution des étapes de l’API pour exécuter les étapes du Workflow sur le serveur d’API. Les brokers PubSub en mode push, tels que Google Cloud Pub/Sub, peuvent également transmettre des événements directement au point de terminaison correspondant de l’API. Ce chemin d’intégration est distinct de celui des Workers en mode pull, qui récupèrent eux-mêmes les événements auprès du broker. Les deux points de terminaison HTTP exigent une authentification lorsqu’un Provider d’authentification est configuré.

Fonctionnement

L’authentification des Workers utilise le même pipeline que le reste de votre serveur Mastra. Le Worker d’orchestration envoie des identifiants avec chaque requête HTTP, et le Provider authenticateToken configuré sur le serveur les valide.

Point de terminaison	Utilisé par	Rôle
POST /api/workflows/:workflowId/runs/:runId/steps/execute	Worker d’orchestration via HttpRemoteStrategy	Exécuter une étape de Workflow sur l’API
POST /api/workflows/events	Brokers en mode push (GCP Pub/Sub, SNS)	Transmettre les événements de Workflow à l’API

Les deux routes ont la valeur requiresAuth: true. Lorsqu’aucun Provider d’authentification n’est configuré, elles sont accessibles publiquement.

attention

Lorsque vous déployez des Workers dans des processus distincts, configurez toujours un Provider d’authentification sur le serveur. Sans celui-ci, tout appelant peut accéder aux points de terminaison d’exécution des étapes et des événements.

Configurer l’authentification des Workers

Configurer un Provider d’authentification sur le serveur

Utilisez n’importe quel Provider d’authentification Mastra. SimpleAuth convient bien aux jetons des Workers :

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      tokens: {
        [process.env.WORKER_TOKEN!]: {
          id: 'worker',
          name: 'Orchestration Worker',
          role: 'worker',
        },
      },
    }),
  },
  // ... storage, pubsub, etc.
})

Définir le jeton du Worker

Dans chaque conteneur de Worker, définissez MASTRA_WORKER_AUTH_TOKEN sur un jeton reconnu par le Provider d’authentification du serveur :

docker-compose.yml

services:
  api:
    environment:
      WORKER_TOKEN: ${WORKER_TOKEN}
      # ... other env vars

  orchestration-worker:
    environment:
      MASTRA_WORKER_AUTH_TOKEN: ${WORKER_TOKEN}
      MASTRA_STEP_EXECUTION_URL: http://api:4111/api # Use HTTPS in production
      # ... other env vars

.env

WORKER_TOKEN=sk-worker-secret-token

Ces exemples utilisent http:// pour le développement local. En production, utilisez des URL HTTPS et terminez TLS à l’aide d’un maillage de services ou d’un contrôleur d’entrée. Consultez les recommandations de sécurité.

Le Worker d’orchestration lit MASTRA_WORKER_AUTH_TOKEN et l’envoie sous forme de jeton Bearer dans l’en-tête Authorization de chaque requête d’exécution d’étape.

Types d’identifiants d’authentification

HttpRemoteStrategy prend en charge trois formats d’identifiants. Le format par défaut (bearer) couvre la plupart des configurations.

Jeton Bearer

Définissez MASTRA_WORKER_AUTH_TOKEN ; la stratégie envoie alors Authorization: Bearer <token> :

MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

En-tête de clé API

Envoyez l’identifiant sous la forme x-worker-api-key plutôt que dans Authorization :

import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: { type: 'api-key', key: process.env.WORKER_API_KEY! },
})

Le Provider d’authentification de votre serveur doit lire l’en-tête x-worker-api-key pour valider cet identifiant.

En-tête personnalisé

Utilisez le nom et la valeur d’en-tête de votre choix :

import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: {
    type: 'header',
    name: 'X-Internal-Service-Key',
    value: process.env.INTERNAL_KEY!,
  },
})

Authentification des brokers en mode push

Lorsque vous utilisez un PubSub en mode push, tel que Google Cloud Pub/Sub, le broker envoie directement les événements par POST au point de terminaison /api/workflows/events. Il joint ses propres identifiants. Par exemple, Google Cloud Pub/Sub envoie un jeton OIDC signé par Google.

Le callback authenticateToken de votre Provider d’authentification doit reconnaître l’identifiant envoyé par le broker. Consultez la documentation de celui-ci pour connaître son mécanisme d’authentification.

Recommandations de sécurité

• Utilisez des jetons différents selon le type de Worker. Vous pouvez ainsi révoquer l’accès d’un Worker sans affecter les autres.
• Renouvelez régulièrement les jetons. Mettez à jour la variable d’environnement WORKER_TOKEN et redémarrez les conteneurs concernés.
• Utilisez TLS en production. La communication entre les Workers et l’API doit passer par HTTPS afin de protéger les jetons en transit. Cela s’applique à tous les environnements, y compris les clusters Kubernetes et les réseaux Docker. Utilisez un maillage de services (par exemple, Istio ou Linkerd) ou une entrée qui termine TLS pour chiffrer le trafic interne.
• Limitez l’accès réseau. Les points de terminaison d’exécution des étapes et des événements sont internes. Dans la mesure du possible, ne les exposez pas à Internet et utilisez des politiques réseau ou des règles de pare-feu.

Pages connexes

• Présentation de l’authentification : Providers disponibles et fonctionnement
• Authentification par jetons : authentification par association des jetons aux utilisateurs
• Déploiement des Workers : configurer des processus de Worker séparés
• Référence des Workers : détails de configuration de tous les types de Worker
• Référence de la CLI : mastra worker build et mastra worker start