MastraAuthOkta and 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 the required environment variables are 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 aren't 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.