メインコンテンツへ移動

MastraAuthOkta クラスと MastraRBACOkta クラス

MastraAuthOkta クラス
MastraAuthOkta クラスへの直接リンク

MastraAuthOkta クラスは、Okta を使用して Mastra の認証を提供します。暗号化されたセッション Cookie を使用する OAuth 2.0 / OIDC ログインフローを実装し、auth オプションを介して Mastra サーバーと統合します。

使用例
使用例への直接リンク

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 エンドポイントの構築に使用されます。

clientId?:

string
= process.env.OKTA_CLIENT_ID
Okta アプリケーションの OAuth クライアント ID。

clientSecret?:

string
= process.env.OKTA_CLIENT_SECRET
OAuth クライアントシークレット。SSO 認可コードフローに必要です。

issuer?:

string
= `https://{domain}/oauth2/default`
トークン発行者の URL。カスタム認可サーバーを使用する場合は、この値を上書きします。

redirectUri?:

string
= process.env.OKTA_REDIRECT_URI
SSO コールバック用の OAuth リダイレクト URI。Okta アプリケーションに設定したリダイレクト URI と一致する必要があります。

scopes?:

string[]
= ['openid', 'profile', 'email', 'groups']
ログインフロー中に要求する OAuth スコープ。

apiToken?:

string
= process.env.OKTA_API_TOKEN
Users API を介したユーザー検索用の Okta API トークン。getUser() が ID に基づいてユーザーデータを返すために必要です。

session?:

OktaSessionOptions
セッション Cookie の設定。
OktaSessionOptions

cookieName?:

string
セッション Cookie の名前。

cookieMaxAge?:

number
Cookie の最大有効期間（秒単位）。

cookiePassword?:

string
セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。設定しない場合は自動生成された値が使用されますが、再起動後には保持されません。

secureCookies?:

boolean
セッション Cookie に Secure フラグを設定します。

name?:

string
= 'okta'
Auth Provider インスタンスのカスタム名。

環境変数
環境変数への直接リンク

コンストラクターオプションが指定されていない場合、次の環境変数が自動的に使用されます。

OKTA_DOMAIN:

string
Okta ドメイン（例：dev-123456.okta.com）。Okta 管理コンソールで確認できます。

OKTA_CLIENT_ID:

string
Okta アプリケーションの OAuth クライアント ID。

OKTA_CLIENT_SECRET:

string
Okta アプリケーションの OAuth クライアントシークレット。

OKTA_ISSUER?:

string
トークン発行者の URL。設定されていない場合、デフォルトは https://{domain}/oauth2/default です。

OKTA_REDIRECT_URI:

string
SSO コールバック用の OAuth リダイレクト URI。

OKTA_COOKIE_PASSWORD?:

string
セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。

OKTA_API_TOKEN?:

string
ユーザー検索と RBAC グループ解決用の Okta API トークン。

認証フロー
認証フローへの直接リンク

MastraAuthOkta は、次の順序でリクエストを認証します。

  1. セッション Cookie：暗号化されたセッション Cookie を読み取り、復号します。セッションが有効で期限切れでない場合、ユーザーは認証されます。
  2. JWT フォールバック：セッション Cookie が存在しない場合、Authorization ヘッダーのトークンを Okta の JWKS エンドポイントに対して検証します。

認証後、authorizeUser はユーザーが有効な oktaId を持っていることを確認します。追加のロジックを実装するには、カスタム authorizeUser 関数を指定します。

OktaUser 型
oktauser-typeへの直接リンク

OktaUser 型は、基本の EEUser インターフェースを Okta 固有のフィールドで拡張します。

id:

string
ユーザー識別子（sub クレームに対応）。

oktaId:

string
Okta ユーザー ID（id と同じ）。

email?:

string
ユーザーのメールアドレス。

name?:

string
トークンクレームから構築されるユーザーの表示名。

avatarUrl?:

string
ユーザーのプロフィール画像の URL。

groups?:

string[]
ユーザーが所属する Okta グループ。groups クレームから設定されます。

MastraRBACOkta クラス
MastraRBACOkta クラスへの直接リンク

MastraRBACOkta クラスは、Okta グループを Mastra 権限にマッピングします。Okta API からユーザーグループを取得し、設定可能なロールマッピングに照らして解決します。MastraAuthOkta またはその他の Auth Provider と組み合わせて使用します。

注記

RBAC には、有効な Enterprise Edition ライセンスが必要です。開発環境ではライセンスなしで動作するためローカルで試せますが、本番環境ではライセンスが必要です。詳細については、営業担当者にお問い合わせください。

使用例
使用例への直接リンク

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

別の Auth Provider で Okta RBAC を使用するには、他の Provider のユーザーオブジェクトから Okta ユーザー ID を解決する getUserId 関数を渡します。

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 グループ名を Mastra 権限文字列の配列にマッピングします。どのグループにも一致しないユーザーに権限を割り当てるには '_default' を使用します。'*'（フルアクセス）や 'agents:*'（Agent に対するすべての操作）のようなワイルドカードをサポートします。

domain?:

string
= process.env.OKTA_DOMAIN
Okta ドメイン。Okta 管理 SDK の初期化に使用されます。

apiToken?:

string
= process.env.OKTA_API_TOKEN
管理 SDK 用の Okta API トークン。Okta API からユーザーグループを取得するために必要です。

getUserId?:

(user: unknown) => string | undefined
ユーザーオブジェクトから Okta ユーザー ID を抽出します。Okta RBAC を別の Auth Provider と組み合わせる場合に使用します。指定されていない場合は、ユーザーオブジェクトの oktaId または id にフォールバックします。

cache?:

PermissionCacheOptions
グループ検索用の LRU キャッシュを設定します。
PermissionCacheOptions

maxSize?:

number
キャッシュするユーザーの最大数。

ttlMs?:

number
有効期間（ミリ秒単位）。
On this page