跳至主要內容

自訂網域 (Custom domains)

備註:

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

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

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

多個自訂網域​

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

依方案限制：

  • 開發租戶：可免費新增最多 2 個自訂網域（僅供測試）
  • 免費方案：可免費新增 1 個自訂網域
  • 專業方案：內含 1 個自訂網域，最多可透過加購擴充至 10 個
  • 企業方案：如需超過 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 供應商而定。過程中可自由切換頁面。

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

網域驗證檔案​

部分第三方平台要求你在網域上放置小型文字或 JSON 檔案以驗證所有權，才能使用其 OAuth、SSO 或其他整合。由於 Logto 自訂網域指向 Logto Cloud，你無法自行上傳檔案至原始主機。Logto 可協助你託管這些檔案。

自訂網域啟用後，於 Console > 設定 > 網域 開啟該網域卡片，使用 網域驗證檔案區塊新增、更新或移除檔案。

支援的路徑

  • 具副檔名的根目錄檔名，如 /MP_verify_xxx.txt 或 /apple-developer-domain-association.txt
  • /.well-known/ 下的路徑，如 /.well-known/apple-developer-domain-association.txt

路徑片段僅允許字母、數字、點、連字號與底線。/.well-known/ 以外不支援巢狀路徑。

限制

  • 每個自訂網域最多 10 個驗證檔案
  • 每檔案內容上限 16,384 字元
  • 僅支援純文字（text/plain）或 JSON（application/json）

儲存後，Logto 會在自訂網域上對 GET 與 HEAD 請求精確回應，例如：

https://auth.example.com/MP_verify_xxx.txt
https://auth.example.com/.well-known/apple-developer-domain-association.txt

既有 Logto 路由優先處理。僅當無其他 Logto 處理器符合路徑時才會回應驗證檔案。

疑難排解​

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 設定更新為使用自訂網域作為端點。

關於「主要網域」：

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（而非 GitHub Dashboard 設定的 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 回應的網域進行設定。

通行密鑰 (Passkey) 用於 MFA 與登入​

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

目前限制：Logto 尚未支援跨網域通行密鑰驗證。若使用者於 auth.us.example.com 註冊通行密鑰，僅能於 auth.us.example.com 登入時使用該通行密鑰進行 MFA 驗證或通行密鑰登入。於一個網域註冊的通行密鑰無法於其他自訂網域登入時使用。