建立自訂權杖宣告腳本

要為 存取權杖 (Access token) 新增自訂宣告，你需要提供一個返回包含這些宣告的物件的腳本。該腳本應寫成返回自訂宣告物件的 JavaScript 函數。

1. 前往 Console > Custom JWT。

2. 有兩種類型的存取權杖可以自訂其宣告：

   • 使用者存取權杖：為終端使用者簽發的存取權杖。例如，用於 Web 應用程式或行動應用程式。
   • 機器對機器存取權杖：為服務或應用程式簽發的存取權杖。例如，用於 機器對機器應用程式。

   不同類型的存取權杖可能有不同的權杖有效負載上下文。你可以分別為每種類型的存取權杖自訂其宣告。

   選擇你想自訂宣告的存取權杖類型，然後點擊 Add custom claims 按鈕來建立新腳本。

備註:

自訂權杖宣告功能僅適用於：

• Logto OSS 使用者
• 具有開發環境的 Logto Cloud 租戶
• 具有生產環境的 Logto Cloud 付費租戶（包括 Pro 租戶和企業租戶）

實作 getCustomJwtClaims() 函數

在 Custom JWT 詳細頁面中，你可以找到編寫自訂權杖宣告腳本的腳本編輯器。該腳本應為返回自訂宣告物件的 JavaScript 函數。

步驟 1：編輯腳本

使用左側的程式碼編輯器來修改腳本。預設提供了一個返回空物件的 getCustomJwtClaims，你可以從這裡開始。你可以修改該函數以返回你自己的自訂宣告物件。

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

此編輯器使用 JavaScript 語言伺服器提供基本的語法高亮、程式碼完成和錯誤檢查。輸入參數已經過良好類型定義並以 jsDoc 風格記錄。你可以使用編輯器的 IntelliSense 正確訪問輸入物件的屬性。你可以在頁面右側找到詳細的參數定義。

備註:

此函數將作為模組匯出。確保函數名稱保持為 getCustomJwtClaims，以便模組能正確匯出該函數。

步驟 2：輸入參數

getCustomJwtClaims 函數接受一個物件作為輸入參數。輸入物件包含以下屬性：

token

權杖有效負載物件。此物件包含你可能需要在腳本中訪問的原始權杖宣告和中繼資料。

你可以在頁面右側找到權杖有效負載物件和使用者資料物件的詳細類型定義。編輯器的 IntelliSense 也將幫助你正確訪問輸入物件的這些屬性。

• 使用者存取權杖資料物件

  屬性	描述	類型
  jti	唯一的 JWT id	string
  aud	權杖的受眾 (Audience)	string
  scope	權杖的權限範圍 (Scopes)	string
  clientId	權杖的客戶端 id	string
  accountId	權杖的使用者 id	string
  expiresWithSession	權杖是否會隨會話過期	boolean
  grantId	權杖的當前驗證授權 id	string
  gty	權杖的授權類型	string
  kind	權杖類型	AccessToken

• 機器對機器存取權杖資料物件

  屬性	描述	類型
  jti	唯一的 JWT id	string
  aud	權杖的受眾 (Audience)	string
  scope	權杖的權限範圍 (Scopes)	string
  clientId	權杖的客戶端 id	string
  kind	權杖類型	ClientCredentials

context（僅適用於使用者存取權杖）

上下文物件包含與當前授權過程相關的使用者資料和授權資料。

• 使用者資料物件 對於使用者存取權杖，Logto 提供額外的使用者資料上下文供你訪問。使用者資料物件包含你可能需要設置自訂宣告的所有使用者資料和組織成員資料。請查看 使用者 和 組織 以獲取更多詳細資訊。
• 授權資料物件 對於通過模擬權杖交換授予的使用者存取權杖，Logto 提供額外的授權資料上下文供你訪問。授權資料物件包含來自主體權杖的自訂上下文。請查看 使用者模擬 以獲取更多詳細資訊。

environmentVariables

使用右側的 Set environment variables 區域來設置腳本的環境變數。你可以使用這些變數來存儲敏感資訊或配置資料，而不需要在腳本中硬編碼。例如，API 金鑰、密鑰或 URL。

你在此處設置的所有環境變數都將在腳本中可用。使用輸入參數中的 environmentVariables 物件來訪問這些變數。

api

api 物件提供了一組實用函數，你可以在腳本中使用這些函數來對權杖簽發過程進行額外的存取控制。api 物件包含以下函數：

api.denyAccess(message?: string): void

api.denyAccess() 函數允許你使用自訂訊息拒絕權杖簽發過程。你可以使用此函數在權杖簽發過程中強制執行額外的存取驗證。

步驟 3：獲取外部資料

你可以使用 Node 內建的 fetch 函數在腳本中獲取外部資料。fetch 函數是一個基於 Promise 的函數，允許你向外部 API 發送 HTTP 請求。

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

備註:

請注意，任何外部資料獲取可能會引入權杖簽發過程的延遲。確保外部 API 可靠且足夠快速以滿足你的需求。

此外：

• 在腳本中妥善處理錯誤和超時，以避免權杖簽發過程被阻塞。
• 使用適當的授權標頭來保護你的外部 API 不被未授權訪問。

步驟 4：測試腳本

在儲存腳本之前，務必測試你的腳本。點擊頁面右側的 Test context 標籤來修改用於測試的模擬權杖有效負載和使用者資料上下文。

點擊編輯器右上角的 Run test 來使用模擬資料運行腳本。腳本的輸出將顯示在 Test Result 抽屜中。

備註:

測試結果是 getCustomJwtClaims 函數在你設置的模擬資料下的輸出（在 序列圖 中完成步驟 3 後獲得的「額外權杖宣告」）。當腳本在權杖簽發過程中執行時，實際的權杖有效負載和使用者資料上下文將有所不同。

點擊 Create 按鈕來儲存腳本。自訂權杖宣告腳本將被儲存並應用於存取權杖簽發過程。