跳至主要內容

自訂網域 (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），並點擊「新增網域」。

    Add domain

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

    Custom domain processing

  4. 等待驗證與 SSL 配置完成。

    1. 我們會每 10 秒自動驗證一次紀錄，直到自訂網域新增成功。請確保輸入的網域名稱與 DNS 紀錄正確無誤。
    2. 驗證通常只需數分鐘，最長可能需 24 小時，視 DNS 供應商而定。過程中可自由切換頁面。

如需新增多個自訂網域，僅需重複上述步驟即可。

疑難排解​

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 文件。

解決方式：你需釋放該區域的 hold 狀態，請依上述連結說明操作。

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

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

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

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

關於「主要網域」：

Logto 沒有獨立的「主要網域」設定。新增自訂網域後，你的自訂網域與預設 {tenant-id}.logto.app 網域都會同時有效。你在 SDK endpoint 參數中設定的網域，將決定驗證 (Authentication) 流程所使用的網域。

解決方式：

將 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（而非 OAuth apps），因 GitHub Apps 支援多個 redirect URI，OAuth apps 僅支援單一 redirect URI。

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

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

步驟：

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

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

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

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

步驟：

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

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

MFA 與登入的 Passkey​

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

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