โครงสร้างข้อมูลตัวเชื่อมต่อ (Connector data structure)

บทนำ

ตัวเชื่อมต่อคืออะไร?

ตัวเชื่อมต่อ (Connector) มีบทบาทสำคัญใน Logto ด้วยความช่วยเหลือของตัวเชื่อมต่อ Logto สามารถให้ผู้ใช้ปลายทางลงทะเบียนหรือเข้าสู่ระบบแบบไม่ใช้รหัสผ่าน รวมถึงความสามารถในการเข้าสู่ระบบด้วยบัญชีโซเชียล ด้วยความนิยมที่เพิ่มขึ้นของเว็บไซต์และแอปพลิเคชัน การเข้าสู่ระบบแบบไม่ใช้รหัสผ่านและโซเชียลช่วยให้ผู้ใช้ไม่ต้องจัดการบัญชีและรหัสผ่านจำนวนมาก

หากคุณต้องการตั้งค่าตัวเชื่อมต่อที่มีอยู่แล้ว โปรดดู คู่มือการตั้งค่าตัวเชื่อมต่อ หากไม่พบตัวเชื่อมต่อที่ต้องการ คุณสามารถพัฒนาตัวเชื่อมต่อเองได้โดยดูจาก คู่มือสำหรับนักพัฒนา

องค์ประกอบ

ข้อมูลของตัวเชื่อมต่อมีคุณสมบัติมากมาย

เพื่อให้การโหลดและอัปเดตข้อมูลมีประสิทธิภาพมากขึ้น เราเก็บข้อมูลบางส่วนของตัวเชื่อมต่อที่มีการเปลี่ยนแปลงบ่อยไว้ในฐานข้อมูล (DB) และส่วนที่เหลือไว้ในเครื่อง (local)

• การจัดเก็บในเครื่อง (Local storage) หรือที่เรียกว่า ConnectorMetadata เป็นอ็อบเจกต์ที่มีคุณสมบัติคงที่ เช่น โลโก้ ประเภทตัวเชื่อมต่อ ฯลฯ (:face_with_monocle: สับสนกับคุณสมบัติเหล่านี้ใช่ไหม? ไม่ต้องกังวล มีคำอธิบายโดยละเอียดด้านล่าง!)
• การจัดเก็บระยะไกล (Remote storage) จะถูกเก็บไว้ใน DB เนื่องจากข้อมูลเหล่านี้มีการเปลี่ยนแปลงค่อนข้างบ่อย

การจัดเก็บในเครื่องของตัวเชื่อมต่อ: ConnectorMetadata

id

id คือคีย์ชนิดสตริงที่ ไม่ซ้ำกัน เพื่อระบุตัวเชื่อมต่อใน Logto

ถูกกำหนดโดยนักพัฒนาของแต่ละตัวเชื่อมต่อและจะถูกอัปโหลดไปยัง DB

target (ชื่อผู้ให้บริการข้อมูลระบุตัวตน)

target คือสตริงตัวพิมพ์เล็กเพื่อแยกแหล่งข้อมูลโซเชียลของตัวเชื่อมต่อโซเชียล

ผู้ใช้ Logto สามารถมองตัวแปรนี้ว่าเป็น "ชื่อผู้ให้บริการข้อมูลระบุตัวตน (Identity provider name)" เพื่อความเข้าใจที่ง่ายขึ้น

ตัวอย่างเช่น target ของคุณควรเป็น google หากคุณเข้าสู่ระบบ Logto ด้วยบัญชี google ของคุณ ค่า target สามารถเป็นสตริงที่ไม่ว่างใด ๆ ก็ได้ แต่เราแนะนำให้ตั้งชื่อให้ตรงไปตรงมาเพราะคุณไม่สามารถเปลี่ยนแปลงได้ เรา ไม่อนุญาต ให้มีตัวเชื่อมต่อหลายตัวที่มี target และ platform เดียวกัน ในทางกลับกัน คุณสามารถมีตัวเชื่อมต่อโซเชียลสำหรับแพลตฟอร์มต่าง ๆ ที่ใช้ target เดียวกันได้ ตัวอย่างเช่น หากผู้ใช้ต้องการเข้าสู่ระบบผ่าน WeChat บนโทรศัพท์ จะต้องมีแอป WeChat แบบ native ตามข้อกำหนดของ WeChat และในขณะเดียวกันก็ต้องมีแอป WeChat แบบ web เพื่อให้เข้าสู่ระบบแอปพลิเคชันเว็บได้ ทั้งสองแอปนี้ใช้ผู้ให้บริการข้อมูลระบุตัวตนเดียวกันและควรมี target เดียวกัน

เราได้สรุปกรณีการใช้งานและข้อแนะนำต่าง ๆ สำหรับผู้ใช้ เนื่องจาก target เป็นแนวคิดที่ซับซ้อน

	ตัวอย่าง	สถานการณ์	ผลลัพธ์	แนะนำหรือไม่
IdP ต่างกันและ target ต่างกัน	1. GitHub Connector (target: github) 2. Google Connector (target: google)	แอปที่รองรับการเข้าสู่ระบบด้วย GitHub และ Google account ทั้งคู่	กรณีใช้งานที่พบบ่อยที่สุด	✅
IdP ต่างกันแต่ target เดียวกัน	1. GitHub Connector (target: github) 2. Google Connector (target: github)	ไม่มี	ผู้ใช้อาจเข้าสู่ระบบบัญชี Logto ที่สร้างด้วยบัญชี GitHub ของผู้ใช้อื่นได้	❌
IdP เดียวกันแต่ target ต่างกัน	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github_oauth)	ตัวเชื่อมต่อ GitHub ใช้กับแอป A ส่วน OAuth GitHub connector สร้างขึ้นเฉพาะสำหรับแอป B	การเข้าสู่ระบบ Logto ด้วยตัวเชื่อมต่อสองตัวนี้จะสร้างบัญชี Logto แยกกันเสมอ แม้จะใช้บัญชี GitHub เดียวกันก็ตาม	การแยกกลุ่มผู้ใช้เป็นกรณีเดียวที่ควรใช้ตัวเชื่อมต่อทั้งสอง อย่างไรก็ตามโดยทั่วไปควรสร้าง tenant แยกกันจะเหมาะสมกว่า
IdP เดียวกันและ target เดียวกัน	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github)	ไม่มี	ใช้ตัวเชื่อมต่อใดก็ได้จะได้ผลลัพธ์เหมือนกัน	การสร้างตัวเชื่อมต่อสองตัวที่ทำงานเหมือนกันอาจสร้างความสับสนให้ผู้ใช้ปลายทางและไม่มีเหตุผล ควรใช้ตัวเชื่อมต่อเดียวที่เหมาะกับกรณีใช้งานของคุณ

type

type คือคุณสมบัติที่บันทึกประเภทของตัวเชื่อมต่อ

เราแบ่งตัวเชื่อมต่อออกเป็น 3 ประเภทตามฟังก์ชันการทำงาน:

• Social: ตัวเชื่อมต่อที่เข้าถึงข้อมูลผู้ใช้จากโซเชียลมีเดียของบุคคลที่สามโดยได้รับการอนุญาตจากผู้ใช้ปลายทาง
• SMS: ตัวเชื่อมต่อที่ช่วยให้ผู้ใช้ปลายทางรับข้อความ SMS บนโทรศัพท์
• Email: ตัวเชื่อมต่อที่ช่วยส่งอีเมลถึงผู้ใช้ปลายทาง

platform

platform ใช้ระบุว่าตัวเชื่อมต่อถูกสร้างขึ้นสำหรับแพลตฟอร์มใด

platform ควรเป็น null หรือหนึ่งในค่าต่อไปนี้ (ชนิดสตริง):

• Native: ตัวเชื่อมต่อที่ใช้ได้เฉพาะกับแอปมือถือ native เท่านั้น
• Web: ตัวเชื่อมต่อที่ใช้ได้เฉพาะกับแอปพลิเคชันเว็บบนเดสก์ท็อป
• Universal: ตัวเชื่อมต่อที่ใช้ได้ทั้งเว็บแอปบนมือถือและเดสก์ท็อป

บันทึก:

platform ของ ตัวเชื่อมต่ออีเมล และ ตัวเชื่อมต่อ SMS ควรเป็น null เสมอ
เฉพาะ ตัวเชื่อมต่อโซเชียล เท่านั้นที่สามารถมีค่า platform ที่ไม่ใช่ NULL ได้

name

name เป็นอ็อบเจกต์ที่ key คือรหัสประเทศ (i18n) และ value คือชื่อที่แสดงของตัวเชื่อมต่อ

description

description ก็เป็นอ็อบเจกต์ที่ key คือรหัสประเทศ (i18n) และ value คือคำอธิบายสั้น ๆ ของตัวเชื่อมต่อ

บันทึก:

เพื่อรองรับการแสดงผลหลายภาษา (i18n) ที่ฝั่งไคลเอนต์ เราเก็บ name (รวมถึง description) เป็น map ที่ใช้รหัสประเทศเป็น key และชื่อ (หรือคำอธิบาย) ในภาษาท้องถิ่นเป็น value

logo

logo คือ URL หรือ path แบบสัมพัทธ์ของโลโก้ตัวเชื่อมต่อ

logoDark

logoDark คือ URL หรือ path แบบสัมพัทธ์ของโลโก้ตัวเชื่อมต่อสำหรับโหมดมืด (nullable)

บันทึก:

logo จำเป็นต้องมีเสมอ ส่วน logoDark เป็นตัวเลือก

เราจะแสดง logo ในโหมดสว่าง และ logoDark ในโหมดมืดถ้ามี หากไม่มีจะ fallback ไปใช้ logo ในโหมดมืด

isStandard

isStandard เป็น attribute แบบ boolean (ไม่บังคับ) เพื่อระบุว่าตัวเชื่อมต่อโซเชียลเป็น "มาตรฐาน" หรือไม่ คุณสามารถระบุ "ตัวเชื่อมต่อมาตรฐาน" ได้จาก attribute isStandard ที่เป็นจริง

บันทึก:

Logto รองรับเฉพาะ "ตัวเชื่อมต่อโซเชียลมาตรฐาน" เท่านั้น กล่าวคือ ตัวเชื่อมต่อ Email หรือ SMS ของ Logto ทั้งหมด ไม่ใช่ "มาตรฐาน"

Logto เรียกตัวเชื่อมต่อที่สร้างบนโปรโตคอลเปิดและมาตรฐาน (เช่น OAuth, OIDC, SAML ฯลฯ) ว่า "ตัวเชื่อมต่อมาตรฐาน" ผู้ใช้ Logto สามารถสร้างอินสแตนซ์หลายตัวบนแต่ละตัวเชื่อมต่อมาตรฐานได้ เช่น หาก Logto มี OAuth standard connector อยู่แล้ว ผู้ใช้สามารถสร้างอินสแตนซ์ "OAuth GitHub connector", "OAuth Google connector" และ "OAuth Facebook connector" ได้ ทั้งหมดนี้อิงกับ OAuth standard connector ของ Logto

หากคุณคุ้นเคยกับการออกแบบตัวเชื่อมต่อของ Logto จะมีได้สูงสุดเพียง 1 ตัวเชื่อมต่อ Email หรือ SMS ในเวลาเดียวกัน ซึ่งหมายความว่า Logto ยังไม่ต้องการ "ตัวเชื่อมต่อ Email หรือ SMS แบบมาตรฐาน" ในขณะนี้

readme

readme คือ path แบบสัมพัทธ์ของไฟล์ README (markdown) ของตัวเชื่อมต่อ ซึ่งเนื้อหาจะถูกแสดงใน "Admin Console" ระหว่างการตั้งค่าตัวเชื่อมต่อ

configTemplate

configTemplate คือ path แบบสัมพัทธ์ของตัวอย่างไฟล์การตั้งค่าตัวเชื่อมต่อ

การจัดเก็บระยะไกลของตัวเชื่อมต่อ: Connector DB {#connectors-remote-storage-connector-db}

id

id ซึ่งทำหน้าที่เป็น primary key ของ Connector DB เป็นคีย์ชนิดสตริงที่สร้างแบบสุ่มเพื่อระบุตัวเชื่อมต่อใน DB

connectorId

connectorId เป็นคีย์ชนิดสตริงและเป็นสะพานเดียวที่เชื่อม Connector DB กับ ConnectorMetadata สำหรับแต่ละคู่ข้อมูล Connector DB และโมดูลโค้ดของตัวเชื่อมต่อ connectorId จะเท่ากับ metadata.id ของโมดูลโค้ดเสมอ

metadata

metadata เป็น subset ของ ConnectorMetadata ซึ่งมี attribute ที่กำหนดค่าได้ เช่น logo, logoDark, target และ name

syncProfile

syncProfile เป็นค่าบูลีนเพื่อกำหนดรูปแบบการอัปเดตโปรไฟล์ผู้ใช้ ค่าเริ่มต้นคือ FALSE

หาก syncProfile เป็น FALSE ข้อมูลพื้นฐานของผู้ใช้ Logto (รวมถึงชื่อและ avatar) จะถูกอัปเดตเฉพาะเมื่อผู้ใช้สมัคร Logto ครั้งแรกผ่านตัวเชื่อมต่อนี้เท่านั้น หากเป็น TRUE ทุกครั้งที่ผู้ใช้เข้าสู่ระบบ Logto ผ่านตัวเชื่อมต่อนี้ โปรไฟล์บัญชี Logto จะถูกอัปเดต

config

config สามารถเป็นอ็อบเจกต์ที่ไม่ว่างใด ๆ ก็ได้

เป็นที่เก็บการตั้งค่าของตัวเชื่อมต่อ แต่ละตัวเชื่อมต่อจะมี property ใน config แตกต่างกัน และต้องผ่านการตรวจสอบความถูกต้อง (แต่ละตัวเชื่อมต่อมีมาตรฐาน "valid" ต่างกัน) ก่อนจะบันทึกลง DB เฉพาะ config ที่ผ่านการตรวจสอบเท่านั้นจึงจะอัปเดตลง DB ได้ มิฉะนั้นจะเกิด error

นักพัฒนาต้อง implement ตัว guard สำหรับ config เมื่อพัฒนาตัวเชื่อมต่อเอง ดูรายละเอียดเพิ่มเติมที่ develop your connector

อยากดูตัวอย่าง config ไหม? ไปที่ connectors หรือหน้าตั้งค่าของแต่ละตัวเชื่อมต่อ

บันทึก:

ใน Logto เวอร์ชันปัจจุบัน สามารถมี Email/SMS connector ได้เพียงตัวเดียวในเวลาเดียวกัน ตัวเชื่อมต่อประเภทเดียวกันตัวอื่น ๆ จะถูกลบโดยอัตโนมัติ

กฎนี้ (มี Email หรือ SMS connector ที่ใช้งานได้เพียงตัวเดียว) ไม่ ใช้กับ ตัวเชื่อมต่อโซเชียล
กล่าวคือ คุณสามารถเพิ่ม ตัวเชื่อมต่อโซเชียล ได้หลายตัว

createdAt

createdAt เป็นสตริง timestamp ที่สร้างอัตโนมัติเพื่อติดตามเวลาที่ตัวเชื่อมต่อถูกสร้างใน DB