@mastra/core/dist/docs/references/reference-auth-okta.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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

```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 you have the appropriately named environment variables 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`)

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