連接器 (Connector) 資料結構
簡介
什麼是連接器 (Connector)？
連接器 (Connectors) 在 Logto 中扮演關鍵角色。透過連接器，Logto 能讓終端使用者使用無密碼註冊或登入，以及支援以社交帳號登入。隨著網站與應用程式日益普及，無密碼與社交登入讓使用者免於管理大量帳號與密碼的困擾。
若你想設定現有連接器，請參考我們的 連接器指南。若找不到你想要的連接器，也可以依照 開發你的連接器 的指引自行開發。
組成
連接器資料中包含許多屬性。
為了提升資料載入與更新效率，我們將經常變動的部分連接器資料存於資料庫（DB），其餘則本地儲存。
- 本地儲存，也稱為 ConnectorMetadata，是一個包含固定屬性的物件，例如 logo、連接器類型等。(:face_with_monocle: 看不懂這些屬性嗎？別擔心，後面會有詳細說明！)
- 遠端儲存 則存於資料庫，因為這些資料變動較頻繁。
連接器本地儲存：ConnectorMetadata
id
id 是一個 唯一 的字串型 key，用於在 Logto 中識別連接器。
它由每個連接器的開發者指定，並會上傳至資料庫。
target（身分提供者名稱）
target 是一個小寫字串，用於區分社交連接器的社交身分來源。
Logto 使用者可以將此變數視為「身分提供者名稱 (Identity provider name)」以便理解。
例如，若你用 Google 帳號登入 Logto，target 應為 google。target 的值可以是任意非空字串，但建議保持簡潔，因為無法更改。我們不允許同一 target 與平台下存在多個連接器。另一方面，不同平台的社交連接器可以共用同一 target。例如，若使用者想在手機上以 WeChat 登入，根據 WeChat 條款需有原生 WeChat app，同時也需有 web WeChat app 以支援網頁登入。這兩個 WeChat app 共用同一身分提供者，應有相同 target。
由於 target 概念較複雜，我們總結了不同情境與建議：
| 範例 | 情境 | 結果 | 建議？ | |
|---|---|---|---|---|
| 不同 IdP 且不同 target | 1. GitHub 連接器 (target: github) 2. Google 連接器 (target: google) | 一個同時支援 GitHub 與 Google 登入的應用程式。 | 最常見的情境。 | ✅ |
| 不同 IdP 但相同 target | 1. GitHub 連接器 (target: github) 2. Google 連接器 (target: github) | 不適用 | 使用者可能會用另一個人的 GitHub 帳號登入 Logto 帳號。 | ❌ |
| 相同 IdP 但不同 target | 1. GitHub 連接器 (target: github) 2. OAuth GitHub 連接器 (target: github_oauth) | GitHub 連接器用於應用程式 A，OAuth GitHub 連接器專為應用程式 B 建立。 | 透過這兩個不同連接器登入 Logto 會產生不同的 Logto 帳號，即使用同一 GitHub 帳號。 | 僅在需要分割使用者池時才需這麼做，但一般建議建立兩個不同租戶來處理此情境。 |
| 相同 IdP 且相同 target | 1. GitHub 連接器 (target: github) 2. OAuth GitHub 連接器 (target: github) | 不適用 | 這兩個連接器的結果完全相同。 | 建立兩個功能相同的連接器會讓終端使用者困惑且沒意義，建議只用一個符合需求的連接器。 |
type
type 屬性紀錄連接器的類型。
我們根據功能將連接器分為三種：
- Social：可在終端使用者授權下存取第三方社群媒體資訊的連接器。
- SMS：讓終端使用者能在手機上接收簡訊的連接器。
- Email：可協助發送電子郵件給終端使用者的連接器。
platform
platform 用於識別連接器所屬平台。
platform 應為 null 或下列字串型值之一：
- Native：僅適用於原生行動應用程式的連接器。
- Web：僅適用於桌面網頁應用程式的連接器。
- Universal：可同時用於行動網頁與桌面網頁應用程式的連接器。
email 連接器 與 SMS 連接器 的 platform 應永遠為 null。
僅 social 連接器 可有非 NULL 的 platform 值。
name
name 是一個物件，其 key 為 i18n 國碼，value 為連接器顯示名稱。
description
description 也是一個物件，其 key 為 i18n 國碼，value 為連接器簡短描述。
為支援客戶端 i18n 顯示，我們將 name（以及 description）屬性以 map 形式儲存，key 為國碼，value 為當地語言名稱（或描述）。
logo
logo 是連接器 logo 的 URL 或相對路徑。
logoDark
logoDark 是 可為空 的連接器深色模式 logo 的 URL 或相對路徑。
logo 為必填，logoDark 為選填。
在亮色模式下顯示 logo，若有 logoDark 則在深色模式下顯示，否則深色模式也會顯示 logo。
isStandard
isStandard 是一個選填的布林屬性，用於標示社交連接器是否為「標準」連接器。你可透過 isStandard 屬性為真來識別「標準」連接器。
Logto 僅支援「標準」社交連接器。也就是說，所有 Logto 的 Email 或 SMS 連接器都不是「標準」連接器。
Logto 將基於開放標準協議（如 OAuth、OIDC、SAML 等）建構的連接器稱為「標準」連接器。Logto 使用者可基於此架構建立多個標準連接器實例。例如，若 Logto 已提供 OAuth 標準連接器，使用者可建立「OAuth GitHub 連接器」、「OAuth Google 連接器」與「OAuth Facebook 連接器」等實例，這些皆基於 Logto OAuth 標準連接器。
若你熟悉 Logto 的連接器設計，會知道同一時間最多只能有一個 Email 或 SMS 連接器，因此目前階段 Logto 不需「標準」Email 或 SMS 連接器。
readme
readme 是連接器 README markdown 檔案的相對路徑，內容會在「管理主控台」設定連接器時顯示。
configTemplate
configTemplate 是連接器設定範例的相對路徑。
連接器遠端儲存：Connector DB {#connectors-remote-storage-connector-db}
id
id 作為連接器 DB 的主鍵，是一個隨機產生的字串型 key，用於在資料庫中識別連接器。
connectorId
connectorId 是字串型 key，為 Connector DB 與 ConnectorMetadata 對應的唯一橋樑。每對連接器 DB 資料與連接器程式碼模組，connectorId 必定等於該模組的 metadata.id。
metadata
metadata 是 ConnectorMetadata 的子集，包含可設定屬性，如 logo、logoDark、target 與 name。
syncProfile
syncProfile 是布林值，用於決定使用者資料同步策略，預設為 FALSE。
若 syncProfile 為 FALSE，Logto 使用者的基本資訊（包含名稱與頭像）僅在首次透過此連接器註冊時更新。否則，每次使用者透過此連接器登入 Logto 時，Logto 帳號資料都會被更新。
config
config 可為任意非空物件。
這是連接器儲存其設定的地方。每個連接器的 config 屬性皆不同，且在儲存至資料庫前必須通過驗證（不同連接器對「有效」的標準不同）。僅有通過驗證的 config 才能寫入資料庫，否則會拋出錯誤。
開發者在開發自訂連接器時需實作 config 驗證，詳情請參閱 開發你的連接器。
想看 config 範例？請參考 連接器 或各連接器設定頁。
目前 Logto 僅允許同時存在一個 Email/SMS 連接器，其他同類型連接器會自動刪除。
此唯一 Email 或 SMS 連接器的規則不適用於 Social 連接器。
換句話說，你可以新增多個 Social 連接器。
createdAt
createdAt 是自動產生的時間戳字串，用於追蹤連接器在資料庫中建立的時間。