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 ;
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

npm install @mastra/auth-okta

pnpm

pnpm add @mastra/auth-okta

Yarn

yarn add @mastra/auth-okta

Bun

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 :

src/mastra/index.ts

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 :

src/mastra/index.ts

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 :

src/mastra/index.ts

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

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 :

src/mastra/index.ts

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

Configurez le client pour inclure les identifiants :

lib/mastra-client.ts

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 :

lib/mastra-client.ts

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 pour davantage d’options de configuration.

Effectuer des requêtes authentifiées

MastraClient

src/api/agents.ts

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

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

cURL

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.