跳至主要內容

自訂網域 (Custom domain)

你的 Logto 租戶預設會有一個免費網域 {{tenant-id}}.app.logto。不過，你可以透過使用自訂網域（例如 auth.example.com）來提升使用者體驗與品牌識別度。

自訂網域會用於多個功能：

備註:

在服務上線後變更網域可能會造成問題，因為你的應用程式程式碼與整合可能仍指向舊網域。為確保順利遷移，請在建立正式環境租戶時就設定自訂網域。

在 Console 設定自訂網域​

要在 Logto Console 新增自訂網域，請依下列步驟操作：

  1. 前往 Console > 設定 > 網域。

  2. 在「自訂網域 (Custom Domain)」區塊輸入你的網域名稱並點擊「新增網域 (add domain)」。

    新增網域

  3. 複製表格中的 CNAME 值，並到你的網域 DNS 供應商新增紀錄。

    自訂網域處理中

  4. 等待驗證與 SSL 流程完成。

    1. 系統會每 10 秒自動驗證一次紀錄，直到自訂網域新增完成。只需確保輸入的網域名稱或 DNS 紀錄正確即可。
    2. 驗證通常只需幾分鐘，但視 DNS 供應商情況最長可能需 24 小時。過程中可自由切換頁面。

疑難排解​

SSL 憑證問題​

若在設定自訂網域時遇到 SSL 憑證問題，可能與 DNS 設定中的 CAA 紀錄有關。CAA 紀錄用來指定哪些憑證授權單位（CA）可為你的網域簽發憑證。若你有使用 CAA 紀錄，需授權 "letsencrypt.org" 與 "pki.goog"，Logto 才能簽發 SSL 憑證。

如需排查與解決 CAA 紀錄相關的 SSL 憑證問題，請參考 Cloudflare 的官方文件。

「The hostname is associated with a held zone」錯誤​

若新增自訂網域時出現「The hostname is associated with a held zone, please contact the owner to have the hold removed」錯誤訊息，代表該網域已在 Cloudflare 區域中，且狀態為「Zone Hold」。詳情請參閱 Cloudflare 官方文件。

要解決此問題，需解除 zone hold。請依上述連結說明操作。

使用自訂網域​

完成設定後，你的自訂網域名稱與預設 Logto 網域名稱都會可用於你的租戶。不過，需進行特定設定才能啟用自訂網域名稱。

備註:

本文假設你的自訂網域為 auth.example.com。

自訂網域已新增

更新應用程式的 SDK 端點​

請在 Logto SDK 初始化程式碼中，將端點的網域名稱改為你的自訂網域。

const client = new LogtoClient({
  ...,// 其他選項
  endpoint: 'https://auth.example.com',
});

修改其他應用程式的驗證端點​

若你的應用程式未使用 Logto SDK，則需手動更新其驗證端點。

你可以在以下 well-known URL 查詢驗證端點：

https://auth.example.com/oidc/.well-known/openid-configuration

更新社交連接器的回呼 URI​

當使用者使用自訂網域時，社交連接器的回呼 URI 會自動更新為新網域。不過，你仍需前往社交平台的開發者後台，手動更新回呼 URI。

當使用者使用自訂網域時，社交連接器的回呼 URI 會使用新網域。因此，請務必到社交平台的開發者後台手動更新回呼 URI。