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

# Okta

Le package `@mastra/auth-okta` fournit à Mastra l'authentification et le contrôle d'accès basé sur les rôles au moyen d'Okta. Il prend en charge un flux de connexion OAuth 2.0 / OIDC avec des cookies de session chiffrés et associe les groupes Okta aux autorisations Mastra.

## Prérequis

Ce guide utilise l'authentification Okta. Veillez à :

1. créer un compte Okta sur [okta.com](https://www.okta.com/) ;
2. configurer une application OAuth dans la console d'administration Okta (application web, flux Authorization Code) ;
3. ajouter votre URI de redirection aux URI de redirection de connexion de l'application ;
4. créer un jeton d'API, nécessaire au RBAC.

Vérifiez que vos variables d'environnement sont définies.

```env
OKTA_DOMAIN=dev-123456.okta.com
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_REDIRECT_URI=http://localhost:4111/api/auth/callback
OKTA_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
OKTA_API_TOKEN=your-api-token
```

> **Remarque:** `OKTA_COOKIE_PASSWORD` chiffre les cookies de session. Si cette variable est omise, une valeur générée automatiquement est utilisée et n'est pas conservée après un redémarrage du serveur. Définissez-la explicitement en production.
>
> `OKTA_API_TOKEN` est requis uniquement lorsque vous utilisez `MastraRBACOkta` pour associer des groupes Okta à des autorisations.

## Installation

**npm**:

```bash
npm install @mastra/auth-okta
```

**pnpm**:

```bash
pnpm add @mastra/auth-okta
```

**Yarn**:

```bash
yarn add @mastra/auth-okta
```

**Bun**:

```bash
bun add @mastra/auth-okta
```

## Exemples d'utilisation

### Utilisation de base avec des variables d'environnement

Lorsque les variables d'environnement ci-dessus sont définies, tous les paramètres du constructeur sont facultatifs :

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta } from '@mastra/auth-okta'

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

### Authentification avec RBAC

Ajoutez `MastraRBACOkta` pour associer les groupes Okta aux autorisations Mastra :

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    rbac: new MastraRBACOkta({
      roleMapping: {
        Admin: ['*'],
        Engineering: ['agents:*', 'workflows:*', 'tools:*'],
        Viewer: ['agents:read', 'workflows:read'],
        _default: [], // users with unmapped groups get no permissions
      },
    }),
  },
})
```

### Utilisation avec plusieurs Providers

Utilisez un autre Provider d'authentification (Auth0, Clerk, etc.) pour la connexion et Okta pour le RBAC. Transmettez une fonction `getUserId` afin d'obtenir l'identifiant utilisateur Okta depuis l'objet utilisateur de l'autre Provider :

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
import { MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0(),
    rbac: new MastraRBACOkta({
      getUserId: user => user.metadata?.oktaUserId || user.email,
      roleMapping: {
        Engineering: ['agents:*', 'workflows:*'],
        Admin: ['*'],
        _default: [],
      },
    }),
  },
})
```

> **Remarque:** Pour relier les utilisateurs entre les Providers, stockez l'identifiant utilisateur Okta dans les métadonnées utilisateur de l'autre Provider. Mastra utilise cet identifiant pour récupérer les groupes auprès d'Okta.

Consultez [MastraAuthOkta](https://mastra.zisheng.pro/fr/reference/auth/okta) pour découvrir toutes les options de configuration disponibles.

## Association des rôles

L'option `roleMapping` associe les noms de groupes Okta à des tableaux de chaînes d'autorisation Mastra. Les autorisations suivent le motif `resource:action` et prennent en charge les caractères génériques :

```typescript
const rbac = new MastraRBACOkta({
  roleMapping: {
    // full access to everything
    Admin: ['*'],

    // full access to agents and workflows
    Engineering: ['agents:*', 'workflows:*'],

    // read-only access
    Viewer: ['agents:read', 'workflows:read'],

    // users whose groups don't match any key above
    _default: [],
  },
})
```

La clé `_default` attribue des autorisations aux utilisateurs dont les groupes Okta ne correspondent à aucune autre clé.

## Configuration côté client

Lorsque l'authentification est activée, les requêtes adressées aux routes Mastra doivent être authentifiées. `MastraAuthOkta` utilise le SSO : les utilisateurs s'authentifient donc sur la page de connexion hébergée par Okta. Après la connexion, un cookie de session chiffré est automatiquement défini.

### Session par cookie (recommandé)

Pour les requêtes interorigines (par exemple un frontend sur `:3000` appelant Mastra sur `:4111`), activez la transmission des identifiants CORS sur le serveur Mastra :

```typescript
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    cors: {
      origin: 'http://localhost:3000',
      credentials: true,
    },
  },
})
```

Configurez le client pour inclure les identifiants :

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

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})
```

### Jeton Bearer

Vous pouvez également transmettre un jeton d'accès Okta comme jeton Bearer. Le jeton est vérifié auprès du point de terminaison JWKS d'Okta :

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

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}
```

Consultez le [SDK client Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-client) pour davantage d’options de configuration.

### Effectuer des requêtes authentifiées

**MastraClient**:

```typescript
import { mastraClient } from '../lib/mastra-client'

const agent = mastraClient.getAgent('weatherAgent')
const response = await agent.generate('Weather in London')
console.log(response)
```

**cURL**:

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

## Dépannage

- **Réponse 401 à chaque requête** : vérifiez que votre domaine Okta, votre identifiant client et votre secret client sont corrects. Assurez-vous que l'URI de redirection de votre application Okta correspond à `OKTA_REDIRECT_URI`.
- **Cookies non envoyés entre origines** : définissez `credentials: "include"` dans `MastraClient`, puis configurez `server.cors` avec l'origine de votre frontend et `credentials: true`.
- **Session perdue au redémarrage** : attribuez à `OKTA_COOKIE_PASSWORD` une valeur stable d'au moins 32 caractères. Sans cela, une clé générée automatiquement et modifiée à chaque redémarrage est utilisée.
- **Le RBAC renvoie des autorisations vides** : vérifiez que `OKTA_API_TOKEN` est défini et que le jeton est autorisé à répertorier les groupes d'utilisateurs. Assurez-vous que les noms de groupes dans `roleMapping` correspondent exactement à ceux d'Okta.