Authentification de Studio

Lorsque vous configurez l’authentification sur votre serveur Mastra, Studio affiche automatiquement un écran de connexion et applique le contrôle d’accès. Une seule configuration sécurise l’interface Studio et vos routes d’API.

Sans authentification, Studio et toutes les routes d’API sont accessibles publiquement.

Quand utiliser l’authentification de Studio

• Plusieurs membres de l’équipe doivent interagir avec des Agents, Workflows et Tools au moyen d’un déploiement Studio partagé.
• Des autorisations doivent limiter les personnes capables d’exécuter des Agents, de modifier des Workflows ou de supprimer des Datasets.
• Un écran de connexion (SSO, adresse e-mail et mot de passe, ou les deux) doit contrôler l’accès à votre déploiement Studio.

Démarrage rapide

Ajoutez un Provider d’authentification à la configuration de votre serveur Mastra. Cet exemple utilise Simple Auth pour une configuration minimale :

src/mastra/index.ts

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

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'my-api-key': {
          id: 'user-1',
          name: 'Alice',
          role: 'admin',
        },
      },
    }),
  },
})

Une fois configuré, Studio affiche un écran de connexion et exige une authentification pour toutes les requêtes d’API. Consultez la documentation sur l’authentification pour obtenir la liste complète des Providers pris en charge.

Fonctionnement

La définition de server.auth remplit simultanément deux fonctions :

• Interface Studio : affiche un écran de connexion. Selon le Provider, les utilisateurs se connectent via SSO, avec une adresse e-mail et un mot de passe, ou avec les deux méthodes.
• Routes d’API : exige une authentification pour toutes les routes intégrées (/api/agents/*, /api/workflows/*, etc.) et personnalisées, que les requêtes proviennent de Studio ou d’appels directs à l’API.

Studio détecte les fonctionnalités disponibles en appelant le point de terminaison GET /api/auth/capabilities. La réponse lui indique les méthodes de connexion à afficher et, si l’utilisateur est déjà authentifié, inclut ses informations et ses autorisations.

Transmettre un jeton dans l’URL

Lorsqu’une autre application intègre Studio ou crée un lien vers celui-ci, elle peut transmettre un jeton d’autorisation au moyen du paramètre d’URL auth_header. Cette méthode est utile lorsqu’un hôte externe détient déjà un jeton et souhaite ouvrir une session Studio authentifiée sans afficher l’écran de connexion.

La valeur auth_header renseigne toujours l’en-tête de requête Authorization. Le paramètre ne définit que cet en-tête ; incluez donc dans la valeur tout préfixe de mécanisme attendu par le serveur, tel que Bearer.

Ouvrez Studio en plaçant le jeton dans la chaîne de requête :

https://your-studio-host/?auth_header=Bearer%20your-token

Studio traite le jeton de la manière suivante :

• Il lit auth_header une fois au chargement et envoie sa valeur comme en-tête Authorization avec chaque requête d’API de la session.
• Il supprime auth_header de la barre d’adresse tout en conservant les autres paramètres de requête et le hash.
• Il conserve le jeton uniquement en mémoire et ne l’écrit jamais dans le stockage local ; le jeton reste donc transitoire et ne persiste pas après un rechargement de page.

Le jeton étant transmis dans un paramètre d’URL, l’application hôte est responsable de la génération et de la transmission de cette URL. Les paramètres d’URL peuvent être exposés dans l’historique du navigateur, les en-têtes de référence et les journaux d’accès du serveur.

Contrôle d’accès fondé sur les rôles

RBAC vous permet de contrôler ce que chaque utilisateur peut voir et faire dans Studio. Il est distinct de l’authentification : server.auth détermine l’identité de l’utilisateur, tandis que server.rbac définit ses actions autorisées.

Rôles par défaut

Mastra inclut quatre rôles par défaut. Importez-les depuis @mastra/core/auth/ee :

Rôle	Autorisations
owner	Accès complet (*)
admin	Lecture, écriture et exécution
member	Lecture et exécution
viewer	Lecture seule

Activer RBAC

Utilisez StaticRBACProvider avec les rôles par défaut ou définissez les vôtres :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'
import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      users: {
        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
      },
    }),
    rbac: new StaticRBACProvider({
      roles: DEFAULT_ROLES,
      getUserRoles: user => [user.role],
    }),
  },
})

Lorsque RBAC est actif, Studio masque les actions que l’utilisateur n’est pas autorisé à effectuer. Un utilisateur doté du rôle viewer ne voit pas les boutons de suppression ; un member ne peut pas modifier la configuration des Agents.

Format des autorisations

Les autorisations suivent le modèle {resource}:{action}, avec une limitation facultative à une ressource précise :

Modèle	Signification
*	Accès complet à toutes les ressources
*:read	Lecture de toutes les ressources
agents:*	Toutes les actions sur les Agents
agents:execute	Exécution des Agents uniquement
agents:read:my-id	Lecture d’un Agent précis par son ID

Les ressources comprennent notamment agents, workflows, tools, datasets, memory, scores et observability. Les actions sont read, write, execute et delete.

Associer les rôles d’un Provider externe

Si votre Provider d’identité définit déjà des rôles (par exemple, les organisations Clerk ou les groupes WorkOS), associez-les aux autorisations Mastra avec roleMapping :

src/mastra/index.ts

import { StaticRBACProvider } from '@mastra/core/auth/ee'

const rbac = new StaticRBACProvider({
  roleMapping: {
    'org:admin': ['*'],
    'org:member': ['*:read', '*:execute'],
    'org:viewer': ['*:read'],
  },
  getUserRoles: user => user.providerRoles,
})

Méthodes de connexion

Studio adapte son écran de connexion au Provider d’authentification :

Type de Provider	Interface de connexion
SSO uniquement	Bouton SSO (par exemple, « Sign in with WorkOS »)
Identifiants uniquement	Formulaire avec adresse e-mail et mot de passe
Les deux	Bouton SSO et formulaire avec adresse e-mail et mot de passe

L’inscription peut être activée ou désactivée pour chaque Provider. Lorsqu’elle est désactivée, Studio masque le lien d’inscription et impose le formulaire de connexion.

Licence EE

Les fonctionnalités d’authentification de Studio (connexion SSO, RBAC et interface fondée sur les autorisations) font partie de Mastra Enterprise Edition. La licence est facultative avec Simple Auth ou lors d’une exécution locale. Les déploiements de production qui utilisent des Providers tiers nécessitent une licence EE valide obtenue auprès de l’équipe commerciale de Mastra.

Pages connexes

• Présentation de l’authentification : liste complète des Providers d’authentification pris en charge.
• Déploiement de Studio : déployer Studio en production.
• Routes d’API personnalisées : contrôler l’authentification de chaque point de terminaison.