Classes MastraAuthOkta et MastraRBACOkta

Classe MastraAuthOkta

La classe MastraAuthOkta fournit une authentification pour Mastra à l’aide d’Okta. Elle implémente un flux de connexion OAuth 2.0 / OIDC avec des cookies de session chiffrés et s’intègre au serveur Mastra par l’intermédiaire de l’option auth.

Exemple d’utilisation

src/mastra/index.ts

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

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta({
      domain: process.env.OKTA_DOMAIN,
      clientId: process.env.OKTA_CLIENT_ID,
      clientSecret: process.env.OKTA_CLIENT_SECRET,
      redirectUri: process.env.OKTA_REDIRECT_URI,
    }),
  },
})

remarque

Vous pouvez omettre les paramètres du constructeur si les variables d’environnement requises sont définies. Dans ce cas, utilisez new MastraAuthOkta() sans argument.

Paramètres du constructeur

domain?:

string

= process.env.OKTA_DOMAIN

Votre domaine Okta (par exemple, dev-123456.okta.com). Utilisé pour construire l’URL de l’émetteur et les endpoints d’API.

clientId?:

string

= process.env.OKTA_CLIENT_ID

L’ID client OAuth de votre application Okta.

clientSecret?:

string

= process.env.OKTA_CLIENT_SECRET

Le secret client OAuth. Requis pour le flux SSO de code d’autorisation.

issuer?:

string

= `https://{domain}/oauth2/default`

L’URL de l’émetteur de jetons. Remplacez-la si vous utilisez un serveur d’autorisation personnalisé.

redirectUri?:

string

= process.env.OKTA_REDIRECT_URI

L’URI de redirection OAuth pour le callback SSO. Elle doit correspondre à l’URI de redirection configurée dans votre application Okta.

scopes?:

string[]

= ['openid', 'profile', 'email', 'groups']

Scopes OAuth à demander pendant le flux de connexion.

apiToken?:

string

= process.env.OKTA_API_TOKEN

Jeton d’API Okta pour rechercher des utilisateurs via l’API Users. Requis pour que getUser() renvoie les données utilisateur par ID.

session?:

OktaSessionOptions

Configuration du cookie de session.

OktaSessionOptions

cookieName?:

string

Nom du cookie de session.

cookieMaxAge?:

number

Durée de vie maximale du cookie, en secondes.

cookiePassword?:

string

Mot de passe pour chiffrer les cookies de session. Il doit comporter au moins 32 caractères. S’il n’est pas défini, une valeur générée automatiquement est utilisée et ne survit pas aux redémarrages.

secureCookies?:

boolean

Définit le marqueur Secure sur les cookies de session.

name?:

string

= 'okta'

Nom personnalisé de l’instance du Provider d’authentification.

Variables d’environnement

Les variables d’environnement suivantes sont automatiquement utilisées lorsque les options du constructeur ne sont pas fournies :

OKTA_DOMAIN:

string

Votre domaine Okta (par exemple, dev-123456.okta.com). Vous le trouverez dans votre console d’administration Okta.

OKTA_CLIENT_ID:

string

L’ID client OAuth de votre application Okta.

OKTA_CLIENT_SECRET:

string

Le secret client OAuth de votre application Okta.

OKTA_ISSUER?:

string

URL de l’émetteur de jetons. Utilise par défaut https://{domain}/oauth2/default si elle n’est pas définie.

OKTA_REDIRECT_URI:

string

URI de redirection OAuth pour le callback SSO.

OKTA_COOKIE_PASSWORD?:

string

Mot de passe pour chiffrer les cookies de session. Il doit comporter au moins 32 caractères.

OKTA_API_TOKEN?:

string

Jeton d’API Okta pour les recherches d’utilisateurs et la résolution des groupes RBAC.

Flux d’authentification

MastraAuthOkta authentifie les requêtes dans l’ordre suivant :

1. Cookie de session : lit et déchiffre le cookie de session chiffré. Si la session est valide et n’a pas expiré, l’utilisateur est authentifié.
2. Solution de repli JWT : si aucun cookie de session n’est présent, vérifie le jeton de l’en-tête Authorization auprès de l’endpoint JWKS d’Okta.

Après l’authentification, authorizeUser vérifie que l’utilisateur possède un oktaId valide. Fournissez une fonction authorizeUser personnalisée pour implémenter une logique supplémentaire.

Type OktaUser

Le type OktaUser étend l’interface de base EEUser avec des champs propres à Okta :

id:

string

Identifiant de l’utilisateur (correspond au claim sub).

oktaId:

string

ID utilisateur Okta (identique à id).

email?:

string

Adresse e-mail de l’utilisateur.

name?:

string

Nom d’affichage de l’utilisateur, construit à partir des claims du jeton.

avatarUrl?:

string

URL de la photo de profil de l’utilisateur.

groups?:

string[]

Groupes Okta auxquels l’utilisateur appartient, renseignés à partir du claim groups.

Classe MastraRBACOkta

La classe MastraRBACOkta associe les groupes Okta aux autorisations Mastra. Elle récupère les groupes d’utilisateurs depuis l’API Okta et les résout par rapport à une association de rôles configurable. Utilisez-la avec MastraAuthOkta ou tout autre Provider d’authentification.

remarque

RBAC requiert une licence Enterprise Edition valide. Il fonctionne sans licence en développement afin que vous puissiez l’essayer localement, mais vous aurez besoin d’une licence en production. Contactez l’équipe commerciale pour plus d’informations.

Exemple d’utilisation

Utilisez MastraRBACOkta avec un Provider d’authentification en le transmettant à l’option rbac :

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: [],
      },
    }),
  },
})

Pour utiliser Okta RBAC avec un autre Provider d’authentification, transmettez une fonction getUserId afin de résoudre l’ID utilisateur Okta à partir de l’objet utilisateur de l’autre Provider :

src/mastra/index.ts

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: [],
      },
    }),
  },
})

Paramètres du constructeur

roleMapping:

RoleMapping

Associe les noms de groupes Okta à des tableaux de chaînes d’autorisation Mastra. Utilisez '_default' pour attribuer des autorisations aux utilisateurs qui ne correspondent à aucun groupe. Prend en charge les caractères génériques tels que '*' (accès complet) et 'agents:*' (toutes les actions d’Agent).

domain?:

string

= process.env.OKTA_DOMAIN

Votre domaine Okta. Utilisé pour initialiser le SDK de gestion Okta.

apiToken?:

string

= process.env.OKTA_API_TOKEN

Jeton d’API Okta pour le SDK de gestion. Requis pour récupérer les groupes d’utilisateurs depuis l’API Okta.

getUserId?:

(user: unknown) => string | undefined

Extrait l’ID utilisateur Okta d’un objet utilisateur. Utilisez cette option lorsque vous combinez Okta RBAC avec un autre Provider d’authentification. Si elle n’est pas fournie, utilise oktaId ou id de l’objet utilisateur.

cache?:

PermissionCacheOptions

Configure le cache LRU pour les recherches de groupes.

PermissionCacheOptions

maxSize?:

number

Nombre maximal d’utilisateurs à mettre en cache.

ttlMs?:

number

Durée de vie en millisecondes.