MastraAuthAuth0 類別

MastraAuthAuth0 類別使用 Auth0 為 Mastra 提供身份驗證。它使用 Auth0 簽發的 JWT token 驗證傳入的請求，並透過 auth 選項與 Mastra 伺服器整合。

使用範例

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0({
      domain: process.env.AUTH0_DOMAIN,
      audience: process.env.AUTH0_AUDIENCE,
    }),
  },
})

備註

如果已設定所需的環境變數（AUTH0_DOMAIN 和 AUTH0_AUDIENCE），便可省略建構函數參數。在這種情況下，使用不帶任何引數的 new MastraAuthAuth0()。

建構函數參數

domain?:

string

= process.env.AUTH0_DOMAIN

你的 Auth0 網域（例如 your-tenant.auth0.com）。這用於驗證由你的 Auth0 租戶簽發的 JWT token。

audience?:

string

= process.env.AUTH0_AUDIENCE

你的 Auth0 API 識別碼／audience。這可確保 token 是為你的特定 API 而簽發。

name?:

string

= "auth0"

身份驗證 Provider 實例的自訂名稱。

authorizeUser?:

(user: Auth0User) => Promise<boolean> | boolean

自訂授權函數，用於判斷是否應授予用戶存取權。此函數會在 token 驗證後呼叫。預設允許所有持有有效 token 且已通過身份驗證的用戶。

環境變數

未提供建構函數選項時，系統會自動使用以下環境變數：

AUTH0_DOMAIN?:

string

你的 Auth0 網域。可在 Auth0 Dashboard 的 Applications > Settings 下找到。

AUTH0_AUDIENCE?:

string

你的 Auth0 API 識別碼。這是你在 Auth0 Dashboard 建立 API 時設定的識別碼。

預設授權行為

預設情況下，MastraAuthAuth0 會驗證 Auth0 JWT token，並允許所有已通過身份驗證的用戶存取：

1. Token 驗證：使用 Auth0 的公鑰（JWKS）驗證 JWT token
2. 簽署驗證：確保 token 由你的 Auth0 租戶簽署
3. 到期檢查：驗證 token 尚未過期
4. Audience 驗證：確認 token 是為你的特定 API（audience）而簽發
5. 簽發者驗證：確保 token 由你的 Auth0 網域簽發

如果所有驗證均通過，該用戶便視為已獲授權。如要實作自訂授權邏輯（例如基於角色的存取控制），請提供自訂 authorizeUser 函數。

Auth0 用戶類型

authorizeUser 函數所使用的 Auth0User 類型對應已解碼的 JWT token payload，通常包括：

• sub：用戶的唯一識別碼（subject）
• email：用戶的電郵地址（如果 token 包含此項）
• email_verified：電郵是否已驗證
• name：用戶的顯示名稱（如有）
• picture：用戶個人資料圖片的 URL（如有）
• iss：Token 簽發者（你的 Auth0 網域）
• aud：Token audience（你的 API 識別碼）
• iat：Token 簽發時間戳記
• exp：Token 到期時間戳記
• scope：授予 token 的 scope
• 在你的 Auth0 租戶中設定的自訂 claim 和應用程式 metadata

實際可用的屬性取決於你的 Auth0 設定、所請求的 scope，以及你設定的任何自訂 claim。

相關內容

MastraAuthAuth0 類別