วิธีสร้าง SAML enterprise SSO ด้วย Next.js (Pages Router)

สำหรับเพื่อนใหม่ของเรา:

Logto คือทางเลือกแทน Auth0 ที่ออกแบบมาสำหรับแอปและผลิตภัณฑ์ SaaS ยุคใหม่ โดยมีทั้งบริการ Cloud และ Open-source เพื่อช่วยให้คุณเปิดตัวระบบการจัดการเอกลักษณ์และการเข้าถึง (IAM) ได้อย่างรวดเร็ว สนุกกับการยืนยันตัวตน (การยืนยันตัวตน), การอนุญาต (การอนุญาต), และการจัดการหลายผู้เช่า ครบจบในที่เดียว

เราแนะนำให้เริ่มต้นด้วย tenant สำหรับการพัฒนาแบบฟรีบน Logto Cloud เพื่อให้คุณสามารถสำรวจฟีเจอร์ทั้งหมดได้อย่างง่ายดาย

ในบทความนี้ เราจะพาคุณไปทีละขั้นตอนเพื่อสร้างประสบการณ์ลงชื่อเข้าใช้ SAML enterprise SSO (การยืนยันตัวตนของผู้ใช้) อย่างรวดเร็วด้วย Next.js (Pages Router) และ Logto

ข้อกำหนดเบื้องต้น

มี Logto instance ที่พร้อมใช้งาน ดู หน้าแนะนำ เพื่อเริ่มต้นใช้งาน
มีความรู้พื้นฐานเกี่ยวกับ Next.js (Pages Router)
มีบัญชี SAML enterprise SSO ที่ใช้งานได้

สร้างแอปพลิเคชันใน Logto

Logto สร้างขึ้นบนพื้นฐานของการยืนยันตัวตน OpenID Connect (OIDC) และการอนุญาต OAuth 2.0 โดยรองรับการจัดการข้อมูลระบุตัวตนแบบรวมศูนย์ข้ามหลายแอปพลิเคชัน ซึ่งมักเรียกว่า การลงชื่อเข้าใช้ครั้งเดียว (Single Sign-On; SSO)

ในการสร้างแอปพลิเคชัน เว็บแบบดั้งเดิม ของคุณ เพียงทำตามขั้นตอนเหล่านี้:

เปิด Logto Console ในส่วน "เริ่มต้นใช้งาน" ให้คลิกที่ลิงก์ "ดูทั้งหมด" เพื่อเปิดรายการเฟรมเวิร์กของแอปพลิเคชัน หรือคุณสามารถไปที่ Logto Console > Applications แล้วคลิกปุ่ม "สร้างแอปพลิเคชัน"
ในหน้าต่างที่เปิดขึ้น ให้คลิกที่ส่วน "เว็บแบบดั้งเดิม" หรือกรองเฟรมเวิร์ก "เว็บแบบดั้งเดิม" ทั้งหมดที่มีโดยใช้ช่องกรองด่วนทางซ้ายมือ จากนั้นคลิกที่การ์ดเฟรมเวิร์ก "Next.js" เพื่อเริ่มสร้างแอปพลิเคชันของคุณ
กรอกชื่อแอปพลิเคชัน เช่น "Bookstore" แล้วคลิก "สร้างแอปพลิเคชัน"

🎉 เยี่ยมมาก! คุณเพิ่งสร้างแอปพลิเคชันแรกของคุณใน Logto คุณจะเห็นหน้าข้อความแสดงความยินดีซึ่งมีคู่มือการเชื่อมต่ออย่างละเอียด ให้ทำตามคู่มือเพื่อดูประสบการณ์ที่จะเกิดขึ้นในแอปพลิเคชันของคุณ

ผสานรวม Next.js กับ Logto

เคล็ดลับ:

โปรเจกต์ตัวอย่างสามารถดูได้ที่ SDK repository ของเรา
ตัวอย่างนี้อ้างอิงจาก Next.js Pages Router

การติดตั้ง

ติดตั้ง Logto SDK ผ่านตัวจัดการแพ็กเกจที่คุณชื่นชอบ:

npm
pnpm
yarn

npm i @logto/next

pnpm add @logto/next

yarn add @logto/next

การเชื่อมต่อระบบ

เริ่มต้น LogtoClient

นำเข้าและเริ่มต้น LogtoClient:

libraries/logto.ts
import LogtoClient from '@logto/next';

export const logtoClient = new LogtoClient({
  appId: '<your-application-id>',
  appSecret: '<your-app-secret-copied-from-console>',
  endpoint: '<your-logto-endpoint>', // เช่น http://localhost:3001
  baseUrl: 'http://localhost:3000',
  cookieSecret: 'complex_password_at_least_32_characters_long',
  cookieSecure: process.env.NODE_ENV === 'production',
});

กำหนดค่า Redirect URIs

ก่อนที่เราจะลงลึกในรายละเอียด นี่คือภาพรวมประสบการณ์ของผู้ใช้ปลายทาง กระบวนการลงชื่อเข้าใช้สามารถสรุปได้ดังนี้:

แอปของคุณเรียกใช้งานเมธอดลงชื่อเข้าใช้
ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้าลงชื่อเข้าใช้ของ Logto สำหรับแอปเนทีฟ ระบบจะเปิดเบราว์เซอร์ของระบบ
ผู้ใช้ลงชื่อเข้าใช้และถูกเปลี่ยนเส้นทางกลับไปยังแอปของคุณ (ตามที่กำหนดไว้ใน redirect URI)

กระบวนการยืนยันตัวตนนี้เป็นไปตามโปรโตคอล OpenID Connect (OIDC) และ Logto บังคับใช้มาตรการรักษาความปลอดภัยอย่างเข้มงวดเพื่อปกป้องการลงชื่อเข้าใช้ของผู้ใช้
หากคุณมีหลายแอป คุณสามารถใช้ผู้ให้บริการข้อมูลระบุตัวตน (Logto) เดียวกันได้ เมื่อผู้ใช้ลงชื่อเข้าใช้แอปหนึ่งแล้ว Logto จะดำเนินการลงชื่อเข้าใช้โดยอัตโนมัติเมื่อผู้ใช้เข้าถึงแอปอื่น

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับเหตุผลและประโยชน์ของการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง โปรดดูที่ อธิบายประสบการณ์การลงชื่อเข้าใช้ของ Logto

บันทึก:

ในตัวอย่างโค้ดต่อไปนี้ เราถือว่าแอปของคุณกำลังทำงานอยู่ที่ http://localhost:3000/

กำหนดค่า Redirect URI

ไปที่หน้ารายละเอียดแอปพลิเคชันใน Logto Console เพิ่ม redirect URI http://localhost:3000/api/logto/sign-in-callback

เช่นเดียวกับการลงชื่อเข้าใช้ ผู้ใช้ควรถูกเปลี่ยนเส้นทางไปที่ Logto เพื่อออกจากเซสชันที่ใช้ร่วมกัน เมื่อเสร็จสิ้นแล้ว ควรเปลี่ยนเส้นทางผู้ใช้กลับไปยังเว็บไซต์ของคุณ ตัวอย่างเช่น เพิ่ม http://localhost:3000/ ในส่วน post sign-out redirect URI

จากนั้นคลิก "Save" เพื่อบันทึกการเปลี่ยนแปลง

เตรียม API routes

เตรียม API routes เพื่อเชื่อมต่อกับ Logto

กลับไปที่ IDE / editor ของคุณ ใช้โค้ดต่อไปนี้เพื่อสร้าง API routes ก่อน:

pages/api/logto/[action].ts
import { logtoClient } from '../../../libraries/logto';

export default logtoClient.handleAuthRoutes();

โค้ดนี้จะสร้าง 4 เส้นทางให้อัตโนมัติ:

/api/logto/sign-in: ลงชื่อเข้าใช้ด้วย Logto
/api/logto/sign-in-callback: จัดการ callback หลังลงชื่อเข้าใช้
/api/logto/sign-out: ลงชื่อออกด้วย Logto
/api/logto/user: ตรวจสอบว่าผู้ใช้ได้รับการยืนยันตัวตนกับ Logto หรือไม่ ถ้าใช่ จะคืนค่าข้อมูลผู้ใช้

เราได้เตรียม API routes แล้ว ต่อไปจะสร้างปุ่มลงชื่อเข้าใช้และลงชื่อออกในหน้าแรกของคุณ โดยต้องเปลี่ยนเส้นทางผู้ใช้ไปยัง route สำหรับลงชื่อเข้าใช้หรือออกเมื่อจำเป็น เพื่อช่วยในส่วนนี้ ให้ใช้ useSWR เพื่อดึงสถานะการยืนยันตัวตนจาก /api/logto/user

ดู คู่มือนี้ เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับ useSWR

/pages/index.tsx
import { type LogtoContext } from '@logto/next';
import useSWR from 'swr';

const Home = () => {
  const { data } = useSWR<LogtoContext>('/api/logto/user');

  return (
    <nav>
      {data?.isAuthenticated ? (
        <p>
          สวัสดี, {data.claims?.sub},
          <button
            onClick={() => {
              window.location.assign('/api/logto/sign-out');
            }}
          >
            ลงชื่อออก
          </button>
        </p>
      ) : (
        <p>
          <button
            onClick={() => {
              window.location.assign('/api/logto/sign-in');
            }}
          >
            ลงชื่อเข้าใช้
          </button>
        </p>
      )}
    </nav>
  );
};

export default Home;

จุดตรวจสอบ: ทดสอบแอปพลิเคชันของคุณ

ตอนนี้คุณสามารถทดสอบแอปพลิเคชันของคุณได้แล้ว:

รันแอปพลิเคชันของคุณ คุณจะเห็นปุ่มลงชื่อเข้าใช้
คลิกปุ่มลงชื่อเข้าใช้ SDK จะเริ่มกระบวนการลงชื่อเข้าใช้และเปลี่ยนเส้นทางคุณไปยังหน้าลงชื่อเข้าใช้ของ Logto
หลังจากที่คุณลงชื่อเข้าใช้แล้ว คุณจะถูกเปลี่ยนเส้นทางกลับไปยังแอปพลิเคชันของคุณและเห็นปุ่มลงชื่อออก
คลิกปุ่มลงชื่อออกเพื่อเคลียร์ที่เก็บโทเค็นและออกจากระบบ

เพิ่มตัวเชื่อมต่อ SAML enterprise SSO

เพื่อให้ง่ายต่อการจัดการการเข้าถึงและได้รับการปกป้องในระดับองค์กรสำหรับลูกค้ารายใหญ่ของคุณ เชื่อมต่อกับ Next.js ในฐานะผู้ให้บริการข้อมูลระบุตัวตนแบบเฟเดอเรต (federated identity provider) ตัวเชื่อมต่อ Logto Enterprise SSO ช่วยให้คุณสร้างการเชื่อมต่อนี้ได้ภายในไม่กี่นาทีโดยการกรอกพารามิเตอร์เพียงไม่กี่รายการ

ในการเพิ่มตัวเชื่อมต่อ Enterprise SSO ให้ทำตามขั้นตอนดังนี้:

ไปที่ Logto console > Enterprise SSO

คลิกปุ่ม "Add enterprise connector" และเลือกประเภทผู้ให้บริการ SSO ของคุณ เลือกจากตัวเชื่อมต่อสำเร็จรูปสำหรับ Microsoft Entra ID (Azure AD), Google Workspace, และ Okta หรือสร้างการเชื่อมต่อ SSO แบบกำหนดเองโดยใช้มาตรฐาน OpenID Connect (OIDC) หรือ SAML
กำหนดชื่อที่ไม่ซ้ำกัน (เช่น SSO sign-in for Acme Company)

ตั้งค่าการเชื่อมต่อกับ IdP ของคุณในแท็บ "Connection" ดูคู่มือด้านบนสำหรับแต่ละประเภทตัวเชื่อมต่อ

ปรับแต่งประสบการณ์ SSO และ โดเมนอีเมล ขององค์กรในแท็บ "Experience" ผู้ใช้ที่ลงชื่อเข้าใช้ด้วยโดเมนอีเมลที่เปิดใช้ SSO จะถูกเปลี่ยนเส้นทางไปยังการยืนยันตัวตน SSO

บันทึกการเปลี่ยนแปลง

ตั้งค่า SAML SSO application on your IdP

ขั้นตอนที่ 1: สร้างแอปพลิเคชัน SAML SSO บน IdP ของคุณ {#step-1-create-a-saml-sso-application-on-your-idp}

เริ่มต้นการผสานรวม SAML Single Sign-On (SSO) โดยการสร้างแอปพลิเคชันในฝั่งผู้ให้บริการข้อมูลระบุตัวตน (IdP). รับค่าการตั้งค่าต่อไปนี้จาก Logto ซึ่งแสดงถึง Service Provider (SP) ของคุณ:

Audience URI (SP Entity ID): ใช้เป็นตัวระบุที่ไม่ซ้ำกันทั่วโลกสำหรับบริการ Logto ของคุณ ทำหน้าที่เป็น EntityId สำหรับ SP ในระหว่างคำขอการยืนยันตัวตน (Authentication request) ไปยัง IdP. ตัวระบุตัวนี้มีความสำคัญต่อการแลกเปลี่ยนข้อมูล SAML assertion และข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตนอื่น ๆ อย่างปลอดภัยระหว่าง IdP กับ Logto
ACS URL: Assertion Consumer Service (ACS) URL คือที่อยู่ที่ SAML assertion จะถูกส่งมาด้วยคำขอแบบ POST. URL นี้ใช้โดย IdP เพื่อส่ง SAML assertion มายัง Logto โดยทำหน้าที่เป็น callback URL ที่ Logto คาดว่าจะได้รับและประมวลผล SAML response ที่มีข้อมูลอัตลักษณ์ของผู้ใช้

กรอกค่า Audience URI และ ACS URL ในแอป SAML ของ IdP ของคุณ และดำเนินการต่อเพื่อดึงค่าการตั้งค่าต่อไปนี้จาก IdP ของคุณ

ขั้นตอนที่ 2: ตั้งค่า SAML SSO บน Logto

เพื่อให้การเชื่อมต่อ SAML SSO ทำงานได้ คุณจะต้องให้ข้อมูลเมทาดาทาของผู้ให้บริการข้อมูลระบุตัวตน (IdP) กับ Logto เมทาดาทา IdP คือเอกสาร XML ที่มีข้อมูลทั้งหมดที่จำเป็นสำหรับ Logto ในการสร้างความเชื่อถือกับ IdP

ไปที่แท็บ Connection Logto มี 3 วิธีในการกำหนดค่าเมทาดาทา IdP ดังนี้:

Metadata URL: ระบุ URL ของเอกสาร IdP metadata XML Logto จะดึงข้อมูลเมทาดาทาจาก URL และกำหนดค่า SAML SSO ให้อัตโนมัติ
Upload Metadata: อัปโหลดเอกสาร IdP metadata XML Logto จะวิเคราะห์เอกสาร XML และกำหนดค่า SAML SSO ให้อัตโนมัติ
Manual Configuration: กำหนดค่าเมทาดาทา IdP ด้วยตนเอง

IdP entity ID: Entity ID ของ IdP
Single sign-on URL: URL ของบริการ Single Sign-On ของ IdP
Signing certificate: ใบรับรอง x509 ใช้สำหรับตรวจสอบลายเซ็นของ SAML response ที่มาจาก IdP

ไม่ว่าคุณจะเลือกวิธีใด Logto จะวิเคราะห์เมทาดาทา IdP และกำหนดค่า SAML SSO ให้สอดคล้องกัน

ขั้นตอนที่ 3: กำหนดการแมปแอตทริบิวต์ของผู้ใช้

แอตทริบิวต์ของผู้ใช้ที่ส่งกลับมาจาก IdP อาจแตกต่างกันไปขึ้นอยู่กับการตั้งค่าของ IdP Logto มีวิธีที่ยืดหยุ่นในการแมปแอตทริบิวต์ของผู้ใช้ที่ได้รับจาก IdP ไปยังแอตทริบิวต์ของผู้ใช้ใน Logto คุณสามารถกำหนดค่าการแมปแอตทริบิวต์ของผู้ใช้ได้ในแท็บประสบการณ์การผสานรวม SAML SSO

id: ตัวระบุเฉพาะของผู้ใช้ Logto จะอ่านการอ้างสิทธิ์ (claim) nameId จาก SAML response เป็นรหัส SSO identity ของผู้ใช้
email: ที่อยู่อีเมลของผู้ใช้
name: ชื่อของผู้ใช้

ขั้นตอนที่ 4: กำหนดโดเมนอีเมลและเปิดใช้งานตัวเชื่อมต่อ SSO

ระบุ email domains ขององค์กรของคุณในแท็บ SSO experience ของตัวเชื่อมต่อ Logto การดำเนินการนี้จะเปิดใช้งานตัวเชื่อมต่อ SSO ให้เป็นวิธีการยืนยันตัวตนสำหรับผู้ใช้เหล่านั้น

ผู้ใช้ที่มีอีเมลในโดเมนที่ระบุจะถูกเปลี่ยนเส้นทางให้ใช้ตัวเชื่อมต่อ SAML SSO เป็นวิธีการยืนยันตัวตนเพียงวิธีเดียว

บันทึกการตั้งค่าของคุณ

โปรดตรวจสอบให้แน่ใจว่าคุณได้กรอกค่าที่จำเป็นในพื้นที่การตั้งค่าตัวเชื่อมต่อ Logto เรียบร้อยแล้ว คลิก "บันทึกและเสร็จสิ้น" (หรือ "บันทึกการเปลี่ยนแปลง") และตัวเชื่อมต่อ SAML enterprise SSO ควรพร้อมใช้งานแล้ว

คุณไม่จำเป็นต้องตั้งค่าตัวเชื่อมต่อองค์กร (enterprise connectors) ทีละตัว Logto ช่วยให้การผสานรวม SSO เข้ากับแอปพลิเคชันของคุณง่ายขึ้นเพียงคลิกเดียว

ไปที่: Console > ประสบการณ์การลงชื่อเข้าใช้ > การสมัครและลงชื่อเข้าใช้
เปิดใช้งานสวิตช์ "SSO สำหรับองค์กร (Enterprise SSO)"
บันทึกการเปลี่ยนแปลง

เมื่อเปิดใช้งานแล้ว จะมีปุ่ม "การลงชื่อเข้าใช้ครั้งเดียว (Single Sign-On)" ปรากฏในหน้าลงชื่อเข้าใช้ของคุณ ผู้ใช้ระดับองค์กรที่มีโดเมนอีเมลที่เปิดใช้งาน SSO สามารถเข้าถึงบริการของคุณผ่านผู้ให้บริการข้อมูลระบุตัวตน (IdPs) ขององค์กรตนเอง

ตรวจจับการลงชื่อเข้าใช้ SSO อัตโนมัติผ่านโดเมนอีเมล

ไปยังหน้าลงชื่อเข้าใช้ SSO ด้วยการคลิกปุ่มลิงก์ด้วยตนเอง

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับประสบการณ์ผู้ใช้ SSO รวมถึง SSO ที่เริ่มต้นโดย SP และ SSO ที่เริ่มต้นโดย IdP โปรดดูที่ User flows: SSO สำหรับองค์กร (Enterprise SSO)

การทดสอบและการตรวจสอบความถูกต้อง

กลับไปที่แอป Next.js (Pages Router) ของคุณ ตอนนี้คุณควรจะสามารถลงชื่อเข้าใช้ด้วย SAML enterprise SSO ได้แล้ว ขอให้สนุก!

อ่านเพิ่มเติม

กระบวนการสำหรับผู้ใช้ปลายทาง: Logto มีโฟลว์การยืนยันตัวตนสำเร็จรูปพร้อมใช้งาน รวมถึง MFA และ Enterprise SSO พร้อม API อันทรงพลังสำหรับการปรับแต่งการตั้งค่าบัญชี การตรวจสอบความปลอดภัย และประสบการณ์แบบหลายผู้เช่า (multi-tenant) ได้อย่างยืดหยุ่น

การอนุญาต (Authorization): การอนุญาต (Authorization) กำหนดว่าผู้ใช้สามารถทำอะไรหรือเข้าถึงทรัพยากรใดได้บ้างหลังจากได้รับการยืนยันตัวตนแล้ว สำรวจวิธีปกป้อง API ของคุณสำหรับแอปเนทีฟและแอปหน้าเดียว (SPA) และการใช้งานการควบคุมการเข้าถึงตามบทบาท (RBAC)

องค์กร (Organizations): ฟีเจอร์องค์กรมีประสิทธิภาพอย่างยิ่งใน SaaS แบบหลายผู้เช่าและแอป B2B โดยช่วยให้สร้างผู้เช่า จัดการสมาชิก RBAC ระดับองค์กร และ Just-in-Time Provisioning ได้

ชุดบทความ Customer IAM: บทความต่อเนื่องเกี่ยวกับการจัดการข้อมูลระบุตัวตนและการเข้าถึงของลูกค้า (Customer IAM) ตั้งแต่ระดับพื้นฐาน 101 ไปจนถึงหัวข้อขั้นสูงและอื่น ๆ

สร้างแอปพลิเคชันใน Logto​

ผสานรวม Next.js กับ Logto​

การติดตั้ง​

การเชื่อมต่อระบบ​

เริ่มต้น LogtoClient​

กำหนดค่า Redirect URIs​

เกี่ยวกับการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง (redirect-based sign-in)​

กำหนดค่า Redirect URI​

เตรียม API routes​

สร้างปุ่มลงชื่อเข้าใช้และลงชื่อออก​

จุดตรวจสอบ: ทดสอบแอปพลิเคชันของคุณ​

เพิ่มตัวเชื่อมต่อ SAML enterprise SSO​

ตั้งค่า SAML SSO application on your IdP​

ขั้นตอนที่ 2: ตั้งค่า SAML SSO บน Logto​

ขั้นตอนที่ 3: กำหนดการแมปแอตทริบิวต์ของผู้ใช้​

ขั้นตอนที่ 4: กำหนดโดเมนอีเมลและเปิดใช้งานตัวเชื่อมต่อ SSO​

บันทึกการตั้งค่าของคุณ​

เปิดใช้งานตัวเชื่อมต่อ SAML enterprise SSO ในประสบการณ์การลงชื่อเข้าใช้​

การทดสอบและการตรวจสอบความถูกต้อง​

อ่านเพิ่มเติม​