跳至主要內容

自訂網域 (Custom domains)

備註:

在服務上線後變更網域可能會造成困擾，因為你的應用程式程式碼與整合可能仍然引用舊網域。為確保順利遷移，建議在建立 Production 租戶時就設定自訂網域。

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

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

多個自訂網域​

Logto 現已支援為單一租戶設定多個自訂網域，讓你的登入頁面可從多個品牌網域存取。

依方案限制：

  • 開發租戶 (Development tenant)：可免費新增最多 2 個自訂網域（僅供測試）
  • 免費方案 (Free plan)：可免費新增 1 個自訂網域
  • 專業方案 (Pro plan)：內含 1 個自訂網域，並可透過加購最多新增至 10 個自訂網域
  • 企業方案 (Enterprise plan)：如需超過 10 個自訂網域或有特殊需求，請聯絡我們

詳情請參閱 Logto 價格表。

多個自訂網域的應用場景：

  • 為不同地區、語系、應用程式、組織或頂級網域使用不同網域
  • 在登入前後維持一致品牌體驗，建立信任
  • 透過 自訂 UI 提供地區或品牌專屬的驗證 (Authentication) 體驗

在 Console 設定自訂網域​

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

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

  2. 在「新增自訂網域」區塊，輸入你的子網域（如 auth.example.com、auth.us.example.com），並點擊「新增網域」。

    新增網域

  3. 複製表格中的 CNAME 值 domains.logto.app，到你的網域 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，請依上述連結說明操作。

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

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

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

若新增自訂網域後出現「redirect URI does not match」錯誤，請將 SDK 設定中的 endpoint 改為自訂網域。

關於「主要網域」：

Logto 並無獨立的「主要網域」設定。新增自訂網域後，你的自訂網域與預設 {tenant-id}.logto.app 網域皆可用。實際驗證 (Authentication) 流程會依你在 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',
});

於 Console > 應用程式 的應用程式詳細頁面，捲動至「端點與憑證」區塊，切換網域下拉選單以檢視並複製對應端點，更新你的應用程式設定。

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

若你的應用程式未使用 Logto SDK，請將其驗證端點更新為自訂網域。

你可於 well-known URL 查詢驗證端點：

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

更新社交連接器的 redirect URI​

社交連接器 採用 OIDC/OAuth 協議。使用者透過自訂網域登入時，redirect URI 會自動使用該網域。你需至社交平台開發者後台更新 redirect URI。

步驟：

  1. 前往 Console > 連接器 > 社交連接器 並選擇你的連接器。
  2. 複製連接器詳情頁顯示的 redirect URI。Logto 會列出所有已設定自訂網域的可用 redirect URI。
  3. 將該 redirect URI 加入社交平台開發者後台（如 Google、GitHub、Facebook）。

多個自訂網域時：

  • 請為每個自訂網域都新增對應的 redirect URI，確保無論使用者從哪個網域登入都能正常社交登入。
  • 預設 Logto 網域（*.logto.app）仍然有效，僅當你希望支援預設網域登入時才需加入。
  • GitHub 連接器請使用 GitHub Apps（而非 GitHub dashboard 的 OAuth apps），因 GitHub Apps 支援多個 redirect URI，OAuth apps 僅支援單一 redirect URI。

更新 OIDC 企業級單一登入 (SSO) 連接器的 redirect URI​

OIDC 企業級連接器 與社交連接器設定方式相同。

步驟：

  1. 前往 Console > 企業級單一登入 (Enterprise SSO) 並選擇你的 OIDC 連接器。
  2. 複製連接器詳情頁的 redirect URI。Logto 會列出所有自訂網域的可用 redirect URI。
  3. 將該 redirect URI 更新至你的身分提供者 (IdP) 設定中。

多個自訂網域時： 請將所有對應的 redirect URI 加入 IdP，確保企業級單一登入 (SSO) 可於所有網域運作。

更新 SAML 企業級單一登入 (SSO) 連接器的 ACS URL​

SAML 企業級連接器 使用 Assertion Consumer Service (ACS) URL 取代 redirect URI。

步驟：

  1. 前往 Console > 企業級單一登入 (Enterprise SSO) 並選擇你的 SAML 連接器。
  2. 在「於 IdP 設定」區塊，透過網域下拉選單切換自訂網域。
  3. 複製你要支援的網域的 ACS URL。
  4. 將這些 ACS URL 加入 SAML 身分提供者設定。

重要： 你選擇的網域會決定使用者 SSO 驗證 (Authentication) 後被導向的位置。請依應用程式預期接收 SAML 回應的網域進行設定。

MFA 的 Passkey​

多重要素驗證 (MFA) 的 Passkey 綁定於註冊時的網域。使用者必須透過相同網域登入才能使用該 Passkey。

目前限制：Logto 尚未支援跨網域 Passkey 驗證 (Authentication)。若使用者於 auth.us.example.com 註冊 Passkey，則必須透過 auth.us.example.com 登入才能使用該 Passkey。於一個網域註冊的 Passkey 無法於其他自訂網域登入時使用。