跳至主要內容

自訂網域 (Custom domain)

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

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

備註:

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

在 Console 設定自訂網域​

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

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

  2. 在「自訂網域 (Custom 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 憑證。

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

「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。請依上述連結說明操作。

Cloudflare 託管網域出現連線逾時（錯誤碼 522）​

若你的網域由 Cloudflare 託管，請將 CNAME 紀錄的 Cloudflare 代理（Proxy）功能關閉。

設定自訂網域後出現「Redirect URI does not match」錯誤​

若新增自訂網域後出現「redirect URI does not match」錯誤，請將 SDK 設定更新為使用自訂網域作為端點。

關於「主要網域 (primary domain)」：

Logto 沒有獨立的「主要網域」設定。新增自訂網域後，你的自訂網域與預設 {tenant-id}.logto.app 網域都會同時有效。實際驗證流程會依你在 SDK endpoint 參數設定的網域為主。

解決方式：

將 SDK 初始化時的 endpoint 參數改為你的自訂網域：

const client = new LogtoClient({
  endpoint: 'https://auth.example.com', // 使用你的自訂網域
  appId: 'your-app-id',
  // ... 其他選項
});

同時請確認 Console → 應用程式 中註冊的 redirect URI 與你實際使用的網域一致。

注意： Logto 會自動為你的自訂網域申請並管理 SSL 憑證，無需自行設定。

使用自訂網域​

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

備註:

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

更新應用程式的 SDK 端點​

請將 Logto SDK 初始化程式碼中的 endpoint 網域名稱修改為自訂網域。

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。