跳到主要内容

MastraAuthOkta 和 MastraRBACOkta 类

MastraAuthOkta 类
MastraAuthOkta 类的直接链接

MastraAuthOkta 类使用 Okta 为 Mastra 提供身份验证。它实现使用加密 Session cookie 的 OAuth 2.0 / OIDC 登录流程，并使用 auth 选项与 Mastra server 集成。

使用示例
使用示例的直接链接

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

如果已设置所需的环境变量，可以省略构造函数参数。在这种情况下，直接使用不带参数的 new MastraAuthOkta()。

构造函数参数
构造函数参数的直接链接

domain?:

string
= process.env.OKTA_DOMAIN
Okta 域（例如 dev-123456.okta.com），用于构造 issuer URL 和 API endpoint。

clientId?:

string
= process.env.OKTA_CLIENT_ID
来自 Okta 应用的 OAuth client ID。

clientSecret?:

string
= process.env.OKTA_CLIENT_SECRET
OAuth client secret。SSO authorization code 流程必需。

issuer?:

string
= `https://{domain}/oauth2/default`
Token issuer URL。使用自定义 authorization server 时请覆盖此值。

redirectUri?:

string
= process.env.OKTA_REDIRECT_URI
SSO callback 的 OAuth redirect URI。必须与 Okta 应用中配置的 redirect URI 一致。

scopes?:

string[]
= ['openid', 'profile', 'email', 'groups']
登录流程中请求的 OAuth scope。

apiToken?:

string
= process.env.OKTA_API_TOKEN
通过 Users API 查找用户所需的 Okta API token。要让 getUser() 按 ID 返回用户数据，必须提供此项。

session?:

OktaSessionOptions
Session cookie 配置。
OktaSessionOptions

cookieName?:

string
Session cookie 的名称。

cookieMaxAge?:

number
Cookie 的最大有效期，单位为秒。

cookiePassword?:

string
用于加密 Session cookie 的密码，长度必须至少为 32 个字符。如果未设置，则会使用自动生成且重启后不会保留的值。

secureCookies?:

boolean
为 Session cookie 设置 Secure 标志。

name?:

string
= 'okta'
Auth Provider 实例的自定义名称。

环境变量
环境变量的直接链接

未提供构造函数选项时，会自动使用以下环境变量：

OKTA_DOMAIN:

string
Okta 域（例如 dev-123456.okta.com），可在 Okta 管理控制台中找到。

OKTA_CLIENT_ID:

string
来自 Okta 应用的 OAuth client ID。

OKTA_CLIENT_SECRET:

string
来自 Okta 应用的 OAuth client secret。

OKTA_ISSUER?:

string
Token issuer URL。未设置时默认为 https://{domain}/oauth2/default。

OKTA_REDIRECT_URI:

string
SSO callback 的 OAuth redirect URI。

OKTA_COOKIE_PASSWORD?:

string
用于加密 Session cookie 的密码，长度必须至少为 32 个字符。

OKTA_API_TOKEN?:

string
用于用户查找和 RBAC group 解析的 Okta API token。

身份验证流程
身份验证流程的直接链接

MastraAuthOkta 按以下顺序对请求进行身份验证：

  1. Session cookie：读取并解密已加密的 Session cookie。如果 Session 有效且未过期，则用户身份验证成功。
  2. JWT fallback：如果不存在 Session cookie，则根据 Okta 的 JWKS endpoint 验证 Authorization header 中的 token。

身份验证完成后，authorizeUser 会检查用户是否具有有效的 oktaId。可以提供自定义 authorizeUser 函数来实现其他逻辑。

OktaUser 类型
oktauser-type的直接链接

OktaUser 类型扩展了基础 EEUser interface，并增加 Okta 专用字段：

id:

string
用户标识符（映射到 sub claim）。

oktaId:

string
Okta user ID（与 id 相同）。

email?:

string
用户电子邮件地址。

name?:

string
根据 token claim 构造的用户显示名称。

avatarUrl?:

string
用户头像的 URL。

groups?:

string[]
用户所属的 Okta group，由 groups claim 填充。

MastraRBACOkta 类
MastraRBACOkta 类的直接链接

MastraRBACOkta 类将 Okta group 映射到 Mastra permission。它从 Okta API 获取用户 group，并根据可配置的 role mapping 进行解析。可以将其与 MastraAuthOkta 或其他 Auth Provider 搭配使用。

备注

RBAC 需要有效的 Enterprise Edition license。在开发环境中无需 license 即可运行，方便本地试用；生产环境则需要 license。有关详细信息，请联系销售团队。

使用示例
使用示例的直接链接

将 MastraRBACOkta 传给 rbac 选项，即可与 Auth Provider 搭配使用：

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

如果要将 Okta RBAC 与其他 Auth Provider 搭配使用，请传入 getUserId 函数，从其他 Provider 的用户对象中解析 Okta user ID：

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

构造函数参数
构造函数参数的直接链接

roleMapping:

RoleMapping
将 Okta group 名称映射到 Mastra permission 字符串数组。使用 '_default' 为不匹配任何 group 的用户分配 permission。支持 '*'（完全访问权限）和 'agents:*'（所有 Agent 操作）等通配符。

domain?:

string
= process.env.OKTA_DOMAIN
Okta 域，用于初始化 Okta management SDK。

apiToken?:

string
= process.env.OKTA_API_TOKEN
Management SDK 使用的 Okta API token。从 Okta API 获取用户 group 时必需。

getUserId?:

(user: unknown) => string | undefined
从用户对象中提取 Okta user ID。将 Okta RBAC 与其他 Auth Provider 组合使用时请提供此项。未提供时，会 fallback 到用户对象中的 oktaId 或 id。

cache?:

PermissionCacheOptions
配置用于 group 查找的 LRU cache。
PermissionCacheOptions

maxSize?:

number
可缓存的最大用户数。

ttlMs?:

number
有效期，单位为毫秒。
On this page