MastraAuthOkta & MastraRBACOkta class

MastraAuthOkta class

The MastraAuthOkta class provides authentication for Mastra using Okta. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies and integrates with the Mastra server using the auth option.

Usage example

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

note

You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use new MastraAuthOkta() without any arguments.

Constructor parameters

domain?:

string

= process.env.OKTA_DOMAIN

Your Okta domain (e.g., `dev-123456.okta.com`). Used to construct the issuer URL and API endpoints.

clientId?:

string

= process.env.OKTA_CLIENT_ID

The OAuth client ID from your Okta application.

clientSecret?:

string

= process.env.OKTA_CLIENT_SECRET

The OAuth client secret. Required for the SSO authorization code flow.

issuer?:

string

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

The token issuer URL. Override this if you use a custom authorization server.

redirectUri?:

string

= process.env.OKTA_REDIRECT_URI

The OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Okta application.

scopes?:

string[]

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

OAuth scopes to request during the login flow.

apiToken?:

string

= process.env.OKTA_API_TOKEN

Okta API token for user lookups via the Users API. Required for `getUser()` to return user data by ID.

session?:

OktaSessionOptions

Session cookie configuration.

OktaSessionOptions

cookieName?:

string

Name of the session cookie.

cookieMaxAge?:

number

Cookie max age in seconds.

cookiePassword?:

string

Password for encrypting session cookies. Must be at least 32 characters. If not set, an auto-generated value is used that does not survive restarts.

secureCookies?:

boolean

Set the `Secure` flag on session cookies.

name?:

string

= 'okta'

Custom name for the auth provider instance.

Environment variables

The following environment variables are automatically used when constructor options are not provided:

OKTA_DOMAIN:

string

Your Okta domain (e.g., `dev-123456.okta.com`). Found in your Okta admin console.

OKTA_CLIENT_ID:

string

The OAuth client ID from your Okta application.

OKTA_CLIENT_SECRET:

string

The OAuth client secret from your Okta application.

OKTA_ISSUER?:

string

Token issuer URL. Defaults to `https://{domain}/oauth2/default` if not set.

OKTA_REDIRECT_URI:

string

OAuth redirect URI for the SSO callback.

OKTA_COOKIE_PASSWORD?:

string

Password for encrypting session cookies. Must be at least 32 characters.

OKTA_API_TOKEN?:

string

Okta API token for user lookups and RBAC group resolution.

Authentication flow

MastraAuthOkta authenticates requests in the following order:

1. Session cookie: Reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
2. JWT fallback: If no session cookie is present, verifies the Authorization header token against Okta's JWKS endpoint.

After authentication, authorizeUser checks that the user has a valid oktaId. Provide a custom authorizeUser function to implement additional logic.

OktaUser type

The OktaUser type extends the base EEUser interface with Okta-specific fields:

id:

string

User identifier (maps to the `sub` claim).

oktaId:

string

Okta user ID (same as `id`).

email?:

string

User email address.

name?:

string

User display name, constructed from token claims.

avatarUrl?:

string

URL to the user's profile picture.

groups?:

string[]

Okta groups the user belongs to, populated from the `groups` claim.

MastraRBACOkta class

The MastraRBACOkta class maps Okta groups to Mastra permissions. It fetches user groups from the Okta API and resolves them against a configurable role mapping. Use it with MastraAuthOkta or any other auth provider.

note

RBAC requires a valid Enterprise Edition license. It works without a license in development so you can try it locally, but you’ll need a license for production. Contact sales for more information.

Usage example

Use MastraRBACOkta alongside an auth provider by passing it to the rbac option:

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

To use Okta RBAC with a different auth provider, pass a getUserId function to resolve the Okta user ID from the other provider's user object:

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

Constructor parameters

roleMapping:

RoleMapping

Maps Okta group names to arrays of Mastra permission strings. Use `'_default'` to assign permissions to users who do not match any group. Supports wildcards like `'*'` (full access) and `'agents:*'` (all agent actions).

domain?:

string

= process.env.OKTA_DOMAIN

Your Okta domain. Used to initialize the Okta management SDK.

apiToken?:

string

= process.env.OKTA_API_TOKEN

Okta API token for the management SDK. Required to fetch user groups from the Okta API.

getUserId?:

(user: unknown) => string | undefined

Extract the Okta user ID from a user object. Use this when combining Okta RBAC with a different auth provider. If not provided, falls back to `oktaId` or `id` on the user object.

cache?:

PermissionCacheOptions

Configure the LRU cache for group lookups.

PermissionCacheOptions

maxSize?:

number

Maximum number of users to cache.

ttlMs?:

number

Time-to-live in milliseconds.