跳至主要內容

應用程式資料結構

簡介​

在 Logto 中，應用程式 指的是註冊於 Logto 平台、並獲授權可存取使用者資訊或代表使用者執行操作的特定軟體程式或服務。應用程式用於識別向 Logto API 發出的請求來源，同時管理使用者存取這些應用程式時的驗證 (Authentication) 與授權 (Authorization) 流程。

在 Logto 的登入體驗 (Sign-in experience) 中使用應用程式，讓使用者能從單一位置輕鬆存取並管理其已授權的應用程式，並享有一致且安全的驗證流程。這有助於簡化使用者體驗，並確保只有經授權的人員能存取敏感資訊或代表組織執行操作。

應用程式也會用於 Logto 的稽核日誌 (Audit logs) 中，以追蹤使用者活動並識別潛在的安全威脅或漏洞。透過將特定操作與特定應用程式關聯，Logto 能提供資料存取與使用的詳細洞察，協助組織更好地管理安全性與合規需求。 如果你想將應用程式整合至 Logto，請參閱 整合 Logto。

屬性​

應用程式 ID​

應用程式 ID 是用於識別你在 Logto 中應用程式的唯一自動產生金鑰，在 OAuth 2.0 中稱為 client id。

備註:

動態應用程式客戶端不會註冊於 Logto。它們的 client ID 是由客戶端擁有的公開 HTTPS URL，該 URL 提供 client metadata 文件。

應用程式類型​

應用程式 可為下列其中一種類型：

  • 原生應用程式 (Native app)：運行於原生環境的應用程式。例如 iOS app、Android app。
    • 裝置流程應用程式 (Device flow app)：一種特殊的原生應用程式，適用於輸入受限裝置或無頭應用（如智慧電視、遊戲主機、CLI 工具、IoT 裝置）。它使用 OAuth 2.0 Device Authorization Grant 取代標準的重導導向流程。詳情請參閱 Device flow 快速入門。
  • 單頁應用程式 (Single page app)：運行於網頁瀏覽器中，能在不重新載入整個頁面的情況下從伺服器取得新資料並更新頁面。例如 React DOM app、Vue app。
  • 傳統網頁應用程式 (Traditional web app)：僅由網頁伺服器渲染與更新頁面的應用程式。例如 JSP、PHP。
  • 機器對機器 (M2M) 應用程式：運行於機器環境、用於直接服務對服務通訊且無需使用者互動的應用程式。

應用程式密鑰​

應用程式密鑰 是用於驗證 (Authentication) 系統中應用程式身分的金鑰，專為私有客戶端（傳統網頁與 M2M 應用程式）作為私密安全防線。

提示:

單頁應用程式 (SPA) 與原生應用程式不提供應用程式密鑰。SPA 與原生應用程式屬於「公開客戶端」，無法安全保存密鑰（瀏覽器程式碼或 app bundle 可被檢查）。Logto 以 PKCE、嚴格的重導 URI / CORS 驗證、短效存取權杖 (Access token) 與重新整理權杖 (Refresh token) 輪替來保護這些應用程式。

應用程式名稱​

應用程式名稱 是應用程式的人類可讀名稱，會顯示於管理主控台。

應用程式名稱 是 Logto 應用程式管理的重要組成部分，讓管理員能輕鬆識別並追蹤平台內各應用程式的活動。

備註:

請注意，應用程式名稱 應謹慎命名，因為所有有權存取管理主控台的使用者都能看到。名稱應準確反映應用程式的用途與功能，並易於理解與辨識。

描述​

應用程式的簡要描述，會顯示於管理主控台的應用程式詳細頁。描述旨在為管理員提供應用程式的額外資訊，例如用途、功能及其他相關細節。

重導 URI​

重導 URI 是預先為應用程式設定的一組有效重導 URI。當使用者登入 Logto 並嘗試存取應用程式時，會被重導至應用程式設定中允許的 URI 之一。

允許的 URI 清單用於驗證應用程式在驗證 (Authentication) 流程中發送給 Logto 的授權請求所包含的重導 URI。若授權請求中的重導 URI 與應用程式設定中的允許 URI 之一相符，則使用者驗證成功後會被重導至該 URI。若重導 URI 不在允許清單中，則不會重導且驗證流程會失敗。

備註:

請務必將所有有效的重導 URI 加入 Logto 應用程式的允許清單，以確保使用者驗證後能順利存取應用程式。

你可以參考 Redirection endpoint 以獲得更多資訊。

了解 OIDC 授權碼流程中的重導 URI

萬用字元模式​

適用於：單頁應用程式、傳統網頁應用程式

重導 URI 支援萬用字元（*）模式，適用於如預覽部署等動態環境。萬用字元可用於 HTTP / HTTPS URI 的主機名稱與路徑部分。

規則：

  • 僅允許在主機名稱與路徑中使用萬用字元
  • 不允許在協定、連接埠、查詢參數或 hash 片段中使用萬用字元
  • 主機名稱萬用字元必須包含至少一個點（例如 https://*.example.com/callback）

範例：

  • https://*.example.com/callback - 匹配任何子網域
  • https://preview-*.example.com/callback - 匹配預覽部署
  • https://example.com/*/callback - 匹配任一路徑片段
警告:

萬用字元重導 URI 並非標準 OIDC，且可能增加攻擊面。請謹慎使用，並盡可能優先使用精確的重導 URI。

登出後重導 URI​

登出後重導 URI 是預先為應用程式設定的一組有效 URI，供使用者自 Logto 登出後重導。

允許的 登出後重導 URI 用於 Logout，屬於 OIDC RP-Initiated（Relying Party Initiated）Logout 規範的一部分。該規範為應用程式發起使用者登出請求提供標準化方法，包含在登出後將使用者重導至預先設定的端點。

當使用者自 Logto 登出時，其工作階段（Session）會被終止，並被重導至應用程式設定中允許的 URI 之一。這確保使用者僅被導向授權且有效的端點，避免將使用者重導至未知或未驗證端點所帶來的未授權存取與安全風險。

你可以參考 RP-initiated logout 以獲得更多資訊。

CORS 允許來源​

CORS（跨來源資源共用）允許來源 是允許應用程式向 Logto 服務發送請求的來源清單。不在允許清單中的來源將無法向 Logto 服務發送請求。

CORS 允許來源清單用於限制未授權網域存取 Logto 服務，並協助防範跨站請求偽造（CSRF）攻擊。透過在 Logto 中為應用程式指定允許來源，服務可確保僅授權網域能發送請求。

備註:

允許來源清單應包含應用程式實際服務的來源。這可確保來自應用程式的請求被允許，而未授權來源的請求會被阻擋。

OpenID 提供者設定端點​

OpenID Connect Discovery 的端點。

授權端點​

授權端點 (Authorization Endpoint) 是 OIDC 術語，是用於啟動使用者驗證 (Authentication) 流程的必要端點。當使用者嘗試存取已註冊於 Logto 平台的受保護資源或應用程式時，會被重導至 授權端點 以驗證身分並獲得存取所請求資源的授權 (Authorization)。

你可以參考 Authorization Endpoint 以獲得更多資訊。

權杖端點​

權杖端點 (Token Endpoint) 是 OIDC 術語，是 OIDC 客戶端用來向 OIDC 提供者取得存取權杖 (Access token)、ID 權杖 (ID token) 或重新整理權杖 (Refresh token) 的 Web API 端點。

當 OIDC 客戶端需要取得存取權杖或 ID 權杖時，會帶著授權憑證（通常是授權碼或重新整理權杖）向權杖端點發送請求。權杖端點驗證授權憑證後，若有效則發放存取權杖或 ID 權杖給客戶端。

你可以參考 Token Endpoint 以獲得更多資訊。

Userinfo 端點​

OpenID Connect UserInfo Endpoint。

永遠發放重新整理權杖 (Always issue refresh token)​

適用於：傳統網頁、SPA

啟用後，Logto 會永遠發放重新整理權杖 (Refresh token)，無論驗證請求中是否帶有 prompt=consent 或權限範圍 (Scope) 中是否帶有 offline_access。

但除非必要（通常僅用於某些需要重新整理權杖的第三方 OAuth 整合），否則不建議這麼做，因為這不符合 OpenID Connect 標準，且可能導致問題。

重新整理權杖輪替 (Rotate refresh token)​

預設值：true

啟用後，當客戶端使用重新整理權杖請求新權杖時，Logto 可能會發放新的重新整理權杖。若重新整理權杖及其 app grant 仍有效，預設輪替政策如下：

  • 僅在重新整理權杖鏈存在未滿一年時可輪替。這是內部輪替安全上限；重新整理權杖本身的 TTL 或 app grant TTL 可能更早到期。達到上限後，Logto 不再輪替重新整理權杖，現有權杖的到期日即為最終期限。
  • 對於未使用 sender-constrained 重新整理權杖的公開客戶端（如一般原生應用程式與單頁應用程式），Logto 只要允許輪替，就會在每次重新整理權杖請求時輪替。
  • 其他客戶端則僅在權杖接近到期時（原始 TTL 已過 70% 以上）才輪替。
備註:

對於公開客戶端，強烈建議為安全考量保持重新整理權杖輪替啟用。

Sender-constrained 重新整理權杖會綁定至客戶端持有的 proof key 或憑證。對於一般 SPA，輪替會發放新權杖但不會延長權杖存活期。新權杖會繼承前一個權杖剩餘的 TTL。

重新整理權杖鏈存活期:

重新整理權杖會與 app grant 綁定。Logto 預設 grant TTL 為 180 天。grant 到期後，重新整理權杖請求會失敗，即使輪替功能仍啟用，該權杖也無法再取得新權杖。

這表示以重新整理權杖支援的授權 (Authorization) 實際最長存活期受限於 grant TTL、明確撤銷或重新整理權杖本身的到期日，以先到者為準。

了解重新整理權杖輪替

重新整理權杖存活期（TTL，天）​

適用於：原生應用程式、傳統網頁、SPA；預設：14 天；最大：180 天

重新整理權杖可用於請求新存取權杖的存活天數，超過後即失效。每次權杖請求會將重新整理權杖的 TTL 延長至此值。

通常建議設較低的值。

備註:

出於安全考量，單頁應用程式（SPA）不支援 TTL 延長。對 SPA 而言，此設定僅控制從最初發放時起的固定權杖存活期。Logto 不會透過權杖請求延長 TTL，輪替也無法防止 SPA 的重新整理權杖過期。

重新整理權杖 TTL 與 grant TTL:

重新整理權杖 TTL 並非唯一的到期限制。重新整理權杖會綁定至 app grant，Logto 預設 grant TTL 為 180 天。grant 到期後，即使重新整理權杖本身仍有效，請求也會失敗。

對於會延長重新整理權杖 TTL 的客戶端，grant TTL 是權杖鏈的絕對最長存活期。對 SPA 而言，重新整理權杖的固定 TTL 可能早於 grant 到期前失效。

重新整理權杖與 Session 綁定:

若在授權請求中未帶上 offline_access 權限範圍 (Scope)，則發放的重新整理權杖會綁定至使用者 Session。Session 固定 TTL 為 14 天。Session 到期後，無論權杖本身 TTL 設定為何，重新整理權杖都會失效。

若要讓重新整理權杖 TTL 設定完全生效，請確保在授權請求中包含 offline_access 權限範圍 (Scope)。

後台登出 URI​

OpenID Connect 後台登出端點。詳情請參閱 聯邦登出：後台登出。

最大允許 grant 數（maxAllowedGrants）​

maxAllowedGrants 是 customClientMetadata 下的可選應用程式層級欄位，用於控制單一使用者於當前應用程式的最大同時有效 grant 數量。

  • 預設值：undefined（無限制）
  • 若有設定：每次授權成功時，Logto 會檢查該使用者於當前應用程式的所有有效 grant（跨瀏覽器與裝置）。若超過上限，Logto 會撤銷最舊的 grant。

此設定適用於你想限制每個應用程式同時登入裝置數量的情境。

每次淘汰都會觸發 Grant.LimitExceeded Webhook 事件，你可通知使用者或追蹤超限頻率。

備註:

此欄位不支援以下類型：

  • 機器對機器應用程式
  • 受保護應用程式
  • SAML 應用程式

自訂資料​

額外的自訂應用程式資訊，不在預設應用程式屬性中列出。使用者可依自身需求定義自訂資料欄位，例如業務專屬設定與配置。