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

# Authentification de Studio

Lorsque vous configurez l’[authentification](https://mastra.zisheng.pro/fr/docs/server/auth) 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](https://mastra.zisheng.pro/fr/docs/server/auth/simple-auth) pour une configuration minimale :

```typescript
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](https://mastra.zisheng.pro/fr/docs/server/auth) pour obtenir la liste complète des Providers pris en charge.

## Fonctionnement

La définition de [`server.auth`](https://mastra.zisheng.pro/fr/reference/configuration) 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 :

```text
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 :

```typescript
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` :

```typescript
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](https://mastra.ai/contact).

## Pages connexes

- [Présentation de l’authentification](https://mastra.zisheng.pro/fr/docs/server/auth) : liste complète des Providers d’authentification pris en charge.
- [Déploiement de Studio](https://mastra.zisheng.pro/fr/docs/studio/deployment) : déployer Studio en production.
- [Routes d’API personnalisées](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes) : contrôler l’authentification de chaque point de terminaison.