ข้ามไปยังเนื้อหาหลัก

นำ UI ของคุณมาใช้

Logto อนุญาตให้คุณนำ UI ของคุณเองมาใช้แทนที่อินเทอร์เฟซประสบการณ์การลงชื่อเข้าใช้ที่มีอยู่โดยสมบูรณ์ นอกเหนือจากตัวเลือกการปรับแต่ง UI ที่สร้างไว้ล่วงหน้า ฟีเจอร์นี้ช่วยให้คุณอัปโหลดไฟล์ zip ที่มี asset UI ที่คุณปรับแต่งเอง (HTML, CSS, JavaScript, รูปภาพ ฯลฯ) ให้ Logto Cloud โฮสต์ไว้บนเซิร์ฟเวอร์ และใช้เป็น ประสบการณ์การลงชื่อเข้าใช้ สำหรับผู้ใช้ tenant ของคุณ

บันทึก:

ฟีเจอร์นี้ต้องการให้ UI ของคุณรองรับ Single Page Application (SPA) และแนะนำให้ใช้ production build เสมอเพื่อประสิทธิภาพสูงสุด

สำรวจฟีเจอร์ Custom UI ใน Logto Console​

เริ่มต้นด้วยโปรเจกต์ทางการ​

วิธีที่เร็วที่สุดในการเริ่มต้น UI ลงชื่อเข้าใช้แบบ custom คือโคลน Logto experience project นี่คือ UI ประสบการณ์การลงชื่อเข้าใช้ของ Logto ที่ครอบคลุมทุกฟีเจอร์และแนวปฏิบัติที่ดีที่สุดของ Logto คุณสามารถปรับแต่งให้เหมาะกับความต้องการของคุณได้

หลังจากตรวจสอบโค้ดแล้ว เพียงรันคำสั่งต่อไปนี้เพื่อ build โปรเจกต์:

pnpm install && pnpm build
บันทึก:

ทั้งโปรเจกต์ Logto เป็น pnpm monorepo หากคุณต้องการรันแพ็กเกจ experience แบบ standalone (โดยไม่ใช้ pnpm) ให้แทนที่ workspace: dependencies ใน package.json ด้วยหมายเลขเวอร์ชันที่ระบุ (เช่น ^1.0.0)

หลังจาก build เสร็จสิ้น คุณจะพบ asset ที่ compile แล้วทั้งหมดในไดเรกทอรี dist จากนั้นสร้าง ZIP archive ของไดเรกทอรี dist - archive นี้จะใช้สำหรับอัปโหลดไปยัง Logto Cloud ในขั้นตอนถัดไป

ข้อกำหนดของ asset UI แบบ custom​

ก่อนอัปโหลด asset UI แบบ custom ของคุณ โปรดตรวจสอบให้แน่ใจว่าตรงตามข้อกำหนดต่อไปนี้:

  • ไฟล์ที่อัปโหลดควรบรรจุเป็น zip ไฟล์เดียว
  • zip ไฟล์ควรมีไฟล์ index.html อยู่ที่ root directory
  • zip ไฟล์ต้องมีขนาดไม่เกิน 20MB
  • zip ไฟล์ต้องไม่มีไฟล์ใดที่มีขนาดเกิน 10MB
  • zip ไฟล์ต้องมีจำนวนไฟล์รวมไม่เกิน 200 ไฟล์

อัปโหลด asset UI แบบ custom ของคุณ​

บันทึก:

โปรดใช้ความระมัดระวังเมื่อใช้ฟีเจอร์นี้ใน production เพราะจะมีผลกับประสบการณ์การลงชื่อเข้าใช้ของผู้ใช้ของคุณทันที

  1. ไปที่ Console > Sign-in & account > Branding > Bring your UI
  2. คลิกเพื่อเลือกหรือ drag & drop zip ไฟล์ที่คุณสร้างไว้ในขั้นตอนก่อนหน้า ระบบจะเริ่มอัปโหลดโดยอัตโนมัติ
  3. เมื่ออัปโหลดเสร็จแล้ว ให้บันทึกการเปลี่ยนแปลง UI แบบ custom ของคุณจะถูกใช้งานทันที
  4. หน้าต่าง "Sign-in preview" จะถูกปิดใช้งานเมื่อคุณใช้ UI ลงชื่อเข้าใช้แบบ custom อย่างไรก็ตาม คุณยังสามารถคลิกปุ่ม "Live preview" เพื่อทดสอบหน้าลงชื่อเข้าใช้แบบ custom ในแท็บเบราว์เซอร์ใหม่ได้

กำหนดค่า CSP แหล่งที่มาแบบ custom​

Logto กำหนด Content Security Policy (CSP) header ให้กับหน้า UI แบบ custom หาก UI ของคุณโหลดสคริปต์จาก third-party หรือเชื่อมต่อกับบริการภายนอก ให้เพิ่ม origin แหล่งที่มาเพิ่มเติมใน Console > Sign-in & account > Branding > Bring your UI

คุณสามารถกำหนดค่าได้ดังนี้:

  • script-src: อนุญาตแหล่งที่มาของ JavaScript module หรือ script เช่น CAPTCHA, analytics, หรือ tag manager provider
  • connect-src: อนุญาต endpoint เครือข่ายที่ใช้โดย fetch, XMLHttpRequest, EventSource และ WebSocket

ตัวอย่าง:

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

ควรใช้ origin แบบ HTTPS สำหรับทั้งสอง directive connect-src ยังรองรับ origin แบบ wss:// สำหรับ WebSocket ด้วย Logto จะเพิ่มแหล่งที่มานี้เข้าไปในนโยบายความปลอดภัยที่มีอยู่เฉพาะเมื่อ asset UI แบบ custom ของคุณถูกใช้งาน

กำหนดค่า Cross-Origin-Opener-Policy header​

โดยปกติ Logto จะไม่ส่ง header Cross-Origin-Opener-Policy (COOP) ดังนั้นแอปที่เปิดหน้าลงชื่อเข้าใช้ใน popup จะยังสามารถสื่อสารกับมันผ่าน window.opener ได้ หากแอปของคุณไม่ได้ลงชื่อเข้าใช้ผ่าน popup คุณสามารถแยก UI ลงชื่อเข้าใช้แบบ custom ของคุณออกจากหน้าต่างเบราว์เซอร์อื่น เลือกนโยบายได้ที่ Cross-Origin-Opener-Policy ใน Console > Sign-in & account > Branding > Bring your UI:

ตัวเลือกHeader ที่ส่งผลลัพธ์
ไม่ตั้งค่า (ไม่มี header)Noneค่าเริ่มต้น ทุกการเชื่อมต่อแบบ popup จะยังทำงานได้ปกติ
same-origin-allow-popupsCross-Origin-Opener-Policy: same-origin-allow-popupsตัดการเชื่อมต่อกับ window ที่เปิดหน้าลงชื่อเข้าใช้ popup ที่ UI ของคุณเปิดจะยังคงมี window.opener ขณะอยู่บนไซต์อื่น
same-originCross-Origin-Opener-Policy: same-originตัดการเชื่อมต่อ popup ที่ UI ของคุณเปิดด้วย

คุณยังสามารถตั้งค่า field crossOriginOpenerPolicy ผ่าน update sign-in experience Management API ได้ โดยรับค่า unsafe-none (ค่าเริ่มต้น, ไม่ส่ง header), same-origin-allow-popups และ same-origin

คำเตือน:

ก่อนเลือกนโยบาย โปรดตรวจสอบว่าแอปของคุณและ UI แบบ custom ใช้งาน popup อย่างไร:

  • แอปที่เปิดหน้าลงชื่อเข้าใช้ใน popup และอาศัย window.opener เช่น รับผลลัพธ์ผ่าน postMessage จะหยุดทำงานหากเลือกนโยบายใดนโยบายหนึ่ง ควรใช้ค่าเริ่มต้นหากยังมีแอปแบบนี้ หรือเปลี่ยนไปใช้ flow ลงชื่อเข้าแบบ redirect ก่อน
  • popup ที่ UI แบบ custom ของคุณเปิดจะสูญเสีย window.opener เมื่อกลับมายัง UI ของคุณ เช่น callback หน้า social sign-in popup ที่ยังอยู่บนไซต์อื่นและส่งผลลัพธ์จากที่นั่น (เช่น popup ลงชื่อเข้าใช้ของ provider) จะยังทำงานกับ same-origin-allow-popups แต่กับ same-origin popup จะสูญเสีย window.opener ทันทีที่เปิด

หากต้องการนโยบาย ให้เลือก same-origin-allow-popups แทน same-origin

Logto จะส่ง header นี้เฉพาะขณะให้บริการ asset UI แบบ custom เท่านั้น หน้าลงชื่อเข้าใช้ที่มีอยู่ /oidc/* และ Account Center (/account) จะไม่ส่ง COOP header ดังนั้นเครื่องมือสแกนความปลอดภัยอาจยังรายงานว่าขาด header นี้ในหน้าดังกล่าว

พัฒนา UI แบบ custom ของคุณ​

โต้ตอบกับ Experience API​

UI แบบ custom ของคุณต้องโต้ตอบกับ Experience API เพื่อดำเนินการต่าง ๆ เช่น ลงชื่อเข้าใช้ สมัครสมาชิก รีเซ็ตรหัสผ่าน ผูกบัญชีโซเชียล เปิดใช้งาน MFA และอื่น ๆ เพื่อเข้าใจ flow ของผู้ใช้และรายละเอียดการใช้งาน แนะนำให้ศึกษาจาก Experience API design RFC ซึ่งมีรายละเอียดทางเทคนิคและตัวอย่างอย่างครบถ้วน

คุณยังต้องเข้าถึงการตั้งค่าประสบการณ์การลงชื่อเข้าใช้อื่น ๆ เช่น สีแบรนด์ โลโก้บริษัท favicon นโยบายรหัสผ่าน ข้อความภาษาท้องถิ่น หรือ custom CSS ผ่าน sign-in Experience API endpoint

จัดการ CAPTCHA เมื่อเปิดใช้งาน​

ประสบการณ์การลงชื่อเข้าใช้ของ Logto ที่มีอยู่จะจัดการ CAPTCHA ให้อัตโนมัติ หาก tenant ของคุณใช้ Bring your UI และเปิดใช้งาน CAPTCHA ป้องกันบอท UI แบบ custom ของคุณต้องทำการเชื่อมต่อ CAPTCHA ฝั่ง frontend ให้เสร็จก่อนเรียก PUT /api/experience

ส่ง provider token ที่ได้กลับไปเป็น captchaToken ใน request body ของ PUT /api/experience ดูคู่มือเฉพาะ provider สำหรับรายละเอียด:

โปรเจกต์ตัวอย่าง​

เรามีชุดโปรเจกต์ตัวอย่างเพื่อช่วยให้คุณเข้าใจและเริ่มต้นสร้าง UI แบบ custom ได้อย่างรวดเร็ว โปรดดูที่ Logto Experience project ใน GitHub สำหรับรายละเอียด

นอกจากนี้ เรายังจะพัฒนาโปรเจกต์ตัวอย่างที่ง่ายขึ้นและเน้นตามสถานการณ์การใช้งานจริงเพื่อครอบคลุม use case ที่พบบ่อย โปรดติดตามอัปเดตในอนาคต!

การพัฒนาและดีบักแบบ local​

สำหรับการพัฒนาและดีบักแบบ local เรามีเครื่องมือ Logto Tunnel CLI เพื่อ:

  • proxy คำขอ Experience API จากเครื่องของคุณไปยัง Logto Cloud endpoint
  • ทดสอบการทำงานของ UI แบบ custom ของคุณแบบ local

ช่วยให้คุณทดสอบและดีบัก UI แบบ custom ได้ก่อนอัปโหลดไปยัง Logto Cloud

โปรดดู ดีบักและทดสอบ UI แบบ custom ของคุณแบบ local สำหรับรายละเอียดเพิ่มเติม

อัปโหลด asset UI แบบ custom ด้วย CLI​

นอกจากการอัปโหลดผ่าน Console แล้ว คุณยังสามารถใช้ Logto CLI เพื่ออัปโหลด asset UI แบบ custom ได้ด้วย วิธีนี้เหมาะสำหรับ workflow การ deploy แบบอัตโนมัติ

โปรดดู อัปโหลด asset UI แบบ custom ด้วย CLI สำหรับรายละเอียดเพิ่มเติม

กู้คืนประสบการณ์การลงชื่อเข้าใช้แบบ built-in ของ Logto​

หากคุณต้องการกู้คืนประสบการณ์การลงชื่อเข้าใช้แบบ built-in ของ Logto เพียงคลิกปุ่มลบบนการ์ด Bring your UI หลังจากบันทึกการเปลี่ยนแปลง UI ลงชื่อเข้าใช้จะกลับไปเป็นค่าเริ่มต้นของ Logto

RFCS: Experience API

 Experience samples Bring your own sign-in UI to Logto Cloud