> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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

```typescript
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`): Your Okta domain (e.g., dev-123456.okta.com). Used to construct the issuer URL and API endpoints. (Default: `process.env.OKTA_DOMAIN`)

**clientId** (`string`): The OAuth client ID from your Okta application. (Default: `process.env.OKTA_CLIENT_ID`)

**clientSecret** (`string`): The OAuth client secret. Required for the SSO authorization code flow. (Default: `process.env.OKTA_CLIENT_SECRET`)

**issuer** (`string`): The token issuer URL. Override this if you use a custom authorization server. (Default: `` `https://{domain}/oauth2/default` ``)

**redirectUri** (`string`): The OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Okta application. (Default: `process.env.OKTA_REDIRECT_URI`)

**audience** (`string | string[]`): Expected aud claim for Bearer tokens. Defaults to the client ID, which matches Okta ID tokens. Set it to the authorization server's audience to accept access tokens, or pass an array to accept several. Does not affect the ID token verified during the SSO login flow, which always uses the client ID. (Default: `process.env.OKTA_AUDIENCE ?? clientId`)

**scopes** (`string[]`): OAuth scopes to request during the login flow. (Default: `['openid', 'profile', 'email', 'groups']`)

**apiToken** (`string`): Okta API token for user lookups via the Users API. Required for getUser() to return user data by ID. (Default: `process.env.OKTA_API_TOKEN`)

**session** (`OktaSessionOptions`): Session cookie configuration.

**session.cookieName** (`string`): Name of the session cookie.

**session.cookieMaxAge** (`number`): Cookie max age in seconds.

**session.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.

**session.secureCookies** (`boolean`): Set the Secure flag on session cookies.

**name** (`string`): Custom name for the auth provider instance. (Default: `'okta'`)

### 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\_AUDIENCE** (`string`): Expected aud claim for Bearer tokens. Defaults to the client ID 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. The token's `iss` claim is checked against `issuer` and its `aud` claim against `audience`.

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](https://mastra.ai/contact) for more information.

### Usage example

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

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

```typescript
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`): Your Okta domain. Used to initialize the Okta management SDK. (Default: `process.env.OKTA_DOMAIN`)

**apiToken** (`string`): Okta API token for the management SDK. Required to fetch user groups from the Okta API. (Default: `process.env.OKTA_API_TOKEN`)

**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.

**cache.maxSize** (`number`): Maximum number of users to cache.

**cache.ttlMs** (`number`): Time-to-live in milliseconds.