Okta Authentication for Mastra

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for integrating Okta OAuth 2.0/OIDC authentication with Mastra, including session cookie management and role-based access control through Okta groups.

Insight

The @mastra/auth-okta package provides Okta-based authentication supporting OAuth 2.0/OIDC login flow with encrypted session cookies. Required environment variables: OKTA_DOMAIN, OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, OKTA_REDIRECT_URI (defaults to /api/auth/callback), OKTA_COOKIE_PASSWORD (encrypts sessions, auto-generated if omitted but doesn’t survive restarts), and OKTA_API_TOKEN (only for MastraRBACOkta RBAC mapping). The package exports MastraAuthOkta for basic authentication and MastraRBACOkta for mapping Okta groups to Mastra permissions. Role mapping uses a resource:action pattern with wildcard support (e.g., agents:, workflows:). The _default key handles users with unmapped groups. MastraRBACOkta can resolve user ID from other auth providers via getUserId function. Session cookies require CORS configuration with credentials: true and origin set to the frontend URL. Clients must use credentials: ‘include’ for cross-origin requests.

Hành động

Install with npm install @mastra/auth-okta. Set required environment variables in .env file. Initialize MastraAuthOkta in Mastra config: new Mastra({ server: { auth: new MastraAuthOkta() } }). For RBAC, add MastraRBACOkta with roleMapping option mapping Okta group names to permission arrays. For cross-origin requests, configure CORS with origin and credentials: true. Use MastraClient with credentials: ‘include’ or pass Okta access token as Bearer header. For cross-provider auth, use a different login provider with MastraRBACOkta for RBAC, passing getUserId function to resolve Okta user ID from other provider’s user object.

Kết quả

Users authenticate through Okta’s hosted login page, receive an encrypted session cookie, and access Mastra routes based on their Okta group memberships mapped to Mastra permissions.

Điều kiện áp dụng

Requires Okta account with OAuth 2.0 Web app configured with Authorization Code grant. OKTA_API_TOKEN is only required when using MastraRBACOkta for RBAC.

Nội dung gốc (Original)

Okta

The @mastra/auth-okta package provides authentication and role-based access control for Mastra using Okta. It supports an OAuth 2.0 / OIDC login flow with encrypted session cookies and maps Okta groups to Mastra permissions.

Prerequisites

This guide uses Okta authentication. Make sure to:

Create an Okta account at okta.com
Set up an OAuth application in the Okta Admin Console (Web app, Authorization Code grant)
Add your redirect URI to the application’s sign-in redirect URIs
Create an API token (required for RBAC)

Make sure your environment variables are set.

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

Note: OKTA_COOKIE_PASSWORD encrypts session cookies. If omitted, an auto-generated value is used that does not survive server restarts. Set it explicitly for production.

OKTA_API_TOKEN is only required when using MastraRBACOkta to map Okta groups to permissions.

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

Usage examples

Basic usage with environment variables

With the environment variables above set, all constructor parameters are optional:

import { Mastra } from '@mastra/core'
import { MastraAuthOkta } from '@mastra/auth-okta'
 
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
  },
})

Auth with RBAC

Add MastraRBACOkta to map Okta groups to Mastra permissions:

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
      },
    }),
  },
})

Cross-provider usage

Use a different auth provider (Auth0, Clerk, etc.) for login and Okta for RBAC. Pass a getUserId function to resolve the Okta user ID from the other provider’s user object:

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

Note: To link users between providers, store the Okta user ID in the other provider’s user metadata. Mastra uses this ID to fetch groups from Okta.

Info: Visit MastraAuthOkta for all available configuration options.

Role mapping

The roleMapping option maps Okta group names to arrays of Mastra permission strings. Permissions follow a resource:action pattern and support wildcards:

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

The _default key assigns permissions to users whose Okta groups do not match any other key.

Client-side setup

When auth is enabled, requests to Mastra routes require authentication. MastraAuthOkta uses SSO, so users authenticate through Okta’s hosted login page. After login, an encrypted session cookie is set automatically.

For cross-origin requests (e.g. a frontend on :3000 calling Mastra on :4111), enable CORS credentials on the Mastra server:

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

Configure the client to include credentials:

import { MastraClient } from '@mastra/client-js'
 
export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})

Bearer token

You can also pass an Okta access token as a Bearer token. The token is verified against Okta’s JWKS endpoint:

import { MastraClient } from '@mastra/client-js'
 
export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}

Info: Visit Mastra Client SDK for more configuration options.

Making authenticated requests

MastraClient:

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"
  }'

Troubleshooting

401 on every request: Verify your Okta domain, client ID, and client secret are correct. Check that the redirect URI in your Okta application matches OKTA_REDIRECT_URI.
Cookies not sent cross-origin: Set credentials: "include" in MastraClient and configure server.cors with your frontend origin and credentials: true.
Session lost on restart: Set OKTA_COOKIE_PASSWORD to a stable value (at least 32 characters). Without it, an auto-generated key is used that changes on each restart.
RBAC returns empty permissions: Verify OKTA_API_TOKEN is set and the token has permission to list user groups. Check that group names in roleMapping match your Okta group names exactly.

Liên kết

Nền tảng: Dev Framework · Mastra
Nguồn: https://mastra.ai/docs/server/auth/okta

KakaFlow KB

Nội dung

Okta Authentication for Mastra

Okta Authentication for Mastra

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Okta

Prerequisites

Installation

Usage examples

Basic usage with environment variables

Auth with RBAC

Cross-provider usage

Role mapping

Client-side setup

Bearer token

Making authenticated requests

Troubleshooting

Liên kết

Sơ đồ

Mục lục

Liên kết ngược

KakaFlow KB

Nội dung

Okta Authentication for Mastra

Okta Authentication for Mastra

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Okta

Prerequisites

Installation

Usage examples

Basic usage with environment variables

Auth with RBAC

Cross-provider usage

Role mapping

Client-side setup

Cookie session (recommended)

Bearer token

Making authenticated requests

Troubleshooting

Liên kết

Sơ đồ

Mục lục

Liên kết ngược