เพิ่มการยืนยันตัวตนให้กับแอป SvelteKit ของคุณ (Add authentication to your SvelteKit application)

เคล็ดลับ:

• ตัวอย่างสาธิตต่อไปนี้สร้างขึ้นบน SvelteKit 2.0.0
• โปรเจกต์ตัวอย่างสามารถดูได้ที่ GitHub repository

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

• บัญชี Logto Cloud หรือ Logto แบบโฮสต์เอง
• สร้างแอปพลิเคชันเว็บแบบดั้งเดิมของ Logto แล้ว

การติดตั้ง

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

npm

npm i @logto/sveltekit

pnpm

pnpm add @logto/sveltekit

yarn

yarn add @logto/sveltekit

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

เพิ่ม Logto hook

ในไฟล์ hooks.server.ts ของคุณ ให้เพิ่มโค้ดต่อไปนี้เพื่อแทรก Logto hook ลงในเซิร์ฟเวอร์ของคุณ:

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    endpoint: '<your-logto-endpoint>',
    appId: '<your-logto-app-id>',
    appSecret: '<your-logto-app-secret>',
  },
  {
    encryptionKey: '<a-random-string>',
  }
);

เนื่องจากข้อมูลเหล่านี้มีความสำคัญ ควรใช้ environment variables:

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';
import { env } from '$env/dynamic/private';

export const handle = handleLogto(
  {
    endpoint: env.LOGTO_ENDPOINT,
    appId: env.LOGTO_APP_ID,
    appSecret: env.LOGTO_APP_SECRET,
  },
  {
    encryptionKey: env.LOGTO_COOKIE_ENCRYPTION_KEY,
  }
);

หากคุณมีหลาย hooks คุณสามารถใช้ ฟังก์ชันช่วย sequence() เพื่อเชื่อมต่อ hooks เหล่านั้น:

hooks.server.ts

import { sequence } from '@sveltejs/kit/hooks';

export const handle = sequence(handleLogto, handleOtherHook);

ตอนนี้คุณสามารถเข้าถึง Logto client ได้ในอ็อบเจกต์ locals สำหรับ TypeScript คุณสามารถเพิ่ม type ใน app.d.ts ได้ดังนี้:

import type { LogtoClient, UserInfoResponse } from '@logto/sveltekit';

declare global {
  namespace App {
    interface Locals {
      logtoClient: LogtoClient;
      user?: UserInfoResponse;
    }
  }
}

เราจะพูดถึงอ็อบเจกต์ user ในภายหลัง

สร้างฟังก์ชันลงชื่อเข้าใช้และออกจากระบบ

บันทึก:

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

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

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

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

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

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

---

กำหนดค่า Redirect URI

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

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

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

ในหน้าที่คุณต้องการสร้างฟังก์ชันลงชื่อเข้าใช้และออกจากระบบ ให้กำหนด actions ดังนี้:

+page.server.ts

import type { Actions } from './$types';

export const actions: Actions = {
  signIn: async ({ locals }) => {
    await locals.logtoClient.signIn('http://localhost:3000/callback');
  },
  signOut: async ({ locals }) => {
    await locals.logtoClient.signOut('http://localhost:3000/');
  },
};

จากนั้นใช้ actions เหล่านี้ใน Svelte component ของคุณ:

+page.svelte

<form method="POST" action="?/{data.user ? 'signOut' : 'signIn'}">
  <button type="submit">Sign {data.user ? 'out' : 'in'}</button>
</form>

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

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

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

รับข้อมูลผู้ใช้

แสดงข้อมูลผู้ใช้

หากต้องการแสดงข้อมูลของผู้ใช้ คุณสามารถ inject อ็อบเจกต์ locals.user เข้าไปใน layout เพื่อให้สามารถใช้งานได้ในทุกหน้า:

+layout.server.ts

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
  return { user: locals.user };
};

ใน Svelte component ของคุณ:

+page.svelte

<script>
  /** @type {import('./$types').PageData} */
  export let data;
</script>

{#if data.user}
<ul>
  {#each Object.entries(data.user) as [key, value]}
  <li>{key}: {value}</li>
  {/each}
</ul>
{/if}

ขอ claims เพิ่มเติม

คุณอาจพบว่าข้อมูลผู้ใช้บางอย่างหายไปในอ็อบเจกต์ที่ส่งคืนจาก locals.user สาเหตุเนื่องจาก OAuth 2.0 และ OpenID Connect (OIDC) ถูกออกแบบมาให้สอดคล้องกับหลักการสิทธิ์น้อยที่สุด (principle of least privilege; PoLP) และ Logto ถูกสร้างขึ้นบนมาตรฐานเหล่านี้

โดยปกติแล้ว จะมีการส่งคืนการอ้างสิทธิ์ (claim) แบบจำกัด หากคุณต้องการข้อมูลเพิ่มเติม คุณสามารถร้องขอขอบเขต (scope) เพิ่มเติมเพื่อเข้าถึงการอ้างสิทธิ์ (claim) ที่มากขึ้นได้

ข้อมูล:

"การอ้างสิทธิ์ (Claim)" คือการยืนยันข้อมูลบางอย่างเกี่ยวกับผู้ถูกอ้างถึง (subject); "ขอบเขต (Scope)" คือกลุ่มของการอ้างสิทธิ์ (claim) ในกรณีนี้ การอ้างสิทธิ์ (claim) คือข้อมูลบางอย่างเกี่ยวกับผู้ใช้

ตัวอย่างที่ไม่เป็นทางการของความสัมพันธ์ระหว่างขอบเขต (scope) กับการอ้างสิทธิ์ (claim) มีดังนี้:

เคล็ดลับ:

การอ้างสิทธิ์ (claim) "sub" หมายถึง "ผู้ถูกอ้างถึง (subject)" ซึ่งคือตัวระบุที่ไม่ซ้ำของผู้ใช้ (เช่น user ID)

Logto SDK จะร้องขอขอบเขต (scope) สามรายการเสมอ ได้แก่ openid, profile และ offline_access

หากต้องการขอ scopes เพิ่มเติม คุณสามารถส่ง scopes ไปที่อ็อบเจกต์ LogtoConfig ในฟังก์ชัน handleLogto:

hooks.server.ts

import { UserScope, handleLogto } from '@logto/sveltekit';

export const handle = handleLogto({
  // ...ตัวเลือกอื่น ๆ
  scopes: [UserScope.email, UserScope.phone], // เพิ่มขอบเขต (scopes) เพิ่มเติมหากต้องการ
});

จากนั้นคุณจะสามารถเข้าถึง claims เพิ่มเติมได้ในอ็อบเจกต์ locals.user

Claims ที่ต้องใช้ network request

เพื่อป้องกันไม่ให้อ็อบเจกต์ user มีขนาดใหญ่เกินไป claims บางรายการจำเป็นต้องใช้ network request เพื่อดึงข้อมูล ตัวอย่างเช่น claim custom_data จะไม่ถูกรวมอยู่ในอ็อบเจกต์ user แม้ว่าจะร้องขอไว้ใน scopes ก็ตาม หากต้องการเข้าถึง claims เหล่านี้ คุณสามารถใช้เมธอด client.fetchUserInfo():

โดยปกติแล้ว อ็อบเจกต์ locals.user เป็นความสะดวกในการเรียกเมธอด getIdTokenClaims แบบ manual หากคุณต้องการใช้ผลลัพธ์จากเมธอด fetchUserInfo คุณสามารถตั้งค่า option fetchUserInfo เป็น true สำหรับ hook ได้ดังนี้:

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    /* Logto config */
  },
  {
    /* Cookie config */
  },
  {
    fetchUserInfo: true,
  }
);

ดึงข้อมูลผู้ใช้ด้วยตนเอง

คุณสามารถใช้เมธอดของ Logto เหล่านี้เพื่อดึงข้อมูลผู้ใช้แบบโปรแกรมมิ่งได้:

• locals.logtoClient.getIdTokenClaims(): รับข้อมูลผู้ใช้โดยการถอดรหัสโทเค็น ID (ID token) ในเครื่อง การอ้างสิทธิ์ (claims) บางรายการอาจไม่มีให้ใช้งาน
• locals.logtoClient.fetchUserInfo(): รับข้อมูลผู้ใช้โดยการส่งคำขอไปยัง จุดปลาย userinfo (userinfo endpoint)

สิ่งสำคัญที่ควรทราบคือ การอ้างสิทธิ์ข้อมูลผู้ใช้ที่สามารถดึงมาได้ขึ้นอยู่กับขอบเขต (scopes) ที่ผู้ใช้เลือกขณะลงชื่อเข้าใช้ และเพื่อประสิทธิภาพและขนาดข้อมูล โทเค็น ID (ID token) อาจไม่มีการอ้างสิทธิ์ของผู้ใช้ทั้งหมด โดยการอ้างสิทธิ์บางรายการจะมีเฉพาะในจุดปลาย userinfo เท่านั้น (ดูรายการที่เกี่ยวข้องด้านล่าง)

ขอบเขต (Scopes) และ การอ้างสิทธิ์ (Claims)

Logto ใช้มาตรฐาน ขอบเขต (scopes) และ การอ้างสิทธิ์ (claims) ของ OIDC เพื่อกำหนดขอบเขตและการอ้างสิทธิ์สำหรับดึงข้อมูลผู้ใช้จากโทเค็น ID (ID token) และ OIDC userinfo endpoint ทั้ง "ขอบเขต (scope)" และ "การอ้างสิทธิ์ (claim)" เป็นคำศัพท์จากข้อกำหนดของ OAuth 2.0 และ OpenID Connect (OIDC)

ต่อไปนี้คือรายการขอบเขต (Scopes) ที่รองรับและการอ้างสิทธิ์ (Claims) ที่เกี่ยวข้อง:

openid

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
sub	string	ตัวระบุที่ไม่ซ้ำของผู้ใช้	ไม่

profile

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
name	string	ชื่อเต็มของผู้ใช้	ไม่
username	string	ชื่อผู้ใช้ของผู้ใช้	ไม่
picture	string	URL ของรูปโปรไฟล์ของผู้ใช้ปลายทาง URL นี้ ต้อง อ้างอิงถึงไฟล์รูปภาพ (เช่น ไฟล์ PNG, JPEG หรือ GIF) ไม่ใช่หน้าเว็บที่มีรูปภาพ โปรดทราบว่า URL นี้ ควร อ้างอิงถึงรูปโปรไฟล์ของผู้ใช้ปลายทางที่เหมาะสมสำหรับการแสดงผลเมื่ออธิบายผู้ใช้ปลายทาง ไม่ใช่รูปภาพใด ๆ ที่ผู้ใช้ถ่ายเอง	ไม่
created_at	number	เวลาที่สร้างผู้ใช้ปลายทาง เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ Unix epoch (1970-01-01T00:00:00Z)	ไม่
updated_at	number	เวลาที่ข้อมูลของผู้ใช้ปลายทางถูกอัปเดตล่าสุด เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ Unix epoch (1970-01-01T00:00:00Z)	ไม่

การอ้างสิทธิ์มาตรฐาน อื่น ๆ เช่น family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, และ locale จะถูกรวมอยู่ในขอบเขต profile ด้วยโดยไม่ต้องร้องขอ endpoint userinfo ความแตกต่างเมื่อเทียบกับการอ้างสิทธิ์ข้างต้นคือ การอ้างสิทธิ์เหล่านี้จะถูกส่งกลับมาเฉพาะเมื่อค่าของมันไม่ว่างเปล่า ในขณะที่การอ้างสิทธิ์ข้างต้นจะส่งกลับ null หากค่าเป็นค่าว่าง

บันทึก:

ต่างจากการอ้างสิทธิ์มาตรฐาน การอ้างสิทธิ์ created_at และ updated_at ใช้หน่วยเป็นมิลลิวินาทีแทนที่จะเป็นวินาที

email

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
email	string	อีเมลของผู้ใช้	ไม่
email_verified	boolean	อีเมลได้รับการยืนยันแล้วหรือไม่	ไม่

phone

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
phone_number	string	หมายเลขโทรศัพท์ของผู้ใช้	ไม่
phone_number_verified	boolean	หมายเลขโทรศัพท์ได้รับการยืนยันแล้วหรือไม่	ไม่

address

โปรดดูรายละเอียดของการอ้างสิทธิ์ที่อยู่ได้ที่ OpenID Connect Core 1.0

custom_data

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
custom_data	object	ข้อมูลกำหนดเองของผู้ใช้	ใช่

identities

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
identities	object	ข้อมูลตัวตนที่เชื่อมโยงของผู้ใช้	ใช่
sso_identities	array	ข้อมูล SSO ที่เชื่อมโยงของผู้ใช้	ใช่

roles

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
roles	string[]	บทบาทของผู้ใช้	ไม่

urn:logto:scope:organizations

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
organizations	string[]	รหัสองค์กรที่ผู้ใช้สังกัด	ไม่
organization_data	object[]	ข้อมูลขององค์กรที่ผู้ใช้สังกัด	ใช่

urn:logto:scope:organization_roles

ชื่อการอ้างสิทธิ์	ประเภท	คำอธิบาย	ต้องใช้ userinfo หรือไม่?
organization_roles	string[]	บทบาทของผู้ใช้ในแต่ละองค์กรในรูปแบบ <organization_id>:<role_name>	ไม่

---

เพื่อประสิทธิภาพและขนาดข้อมูล หาก "ต้องใช้ userinfo หรือไม่?" เป็น "ใช่" หมายความว่าการอ้างสิทธิ์นั้นจะไม่ปรากฏในโทเค็น ID แต่จะถูกส่งกลับใน response ของ userinfo endpoint

ทรัพยากร API และองค์กร

เราแนะนำให้อ่าน 🔐 การควบคุมการเข้าถึงตามบทบาท (RBAC) ก่อน เพื่อทำความเข้าใจแนวคิดพื้นฐานของ RBAC ใน Logto และวิธีตั้งค่าทรัพยากร API อย่างถูกต้อง

กำหนดค่า Logto client

เมื่อคุณตั้งค่า ทรัพยากร API (API resources) เรียบร้อยแล้ว คุณสามารถเพิ่มทรัพยากรเหล่านี้ขณะกำหนดค่า Logto ในแอปของคุณได้:

hooks.server.ts

export const handle = handleLogto(
  {
    // ...การตั้งค่าอื่น ๆ
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // เพิ่มทรัพยากร API
  }
  // ...การตั้งค่าอื่น ๆ
);

แต่ละ ทรัพยากร API (API resource) จะมี สิทธิ์ (scopes) ของตัวเอง

ตัวอย่างเช่น ทรัพยากร https://shopping.your-app.com/api มีสิทธิ์ shopping:read และ shopping:write และทรัพยากร https://store.your-app.com/api มีสิทธิ์ store:read และ store:write

หากต้องการร้องขอสิทธิ์เหล่านี้ คุณสามารถเพิ่มขณะกำหนดค่า Logto ในแอปของคุณได้:

hooks.server.ts

export const handle = handleLogto(
  {
    // ...การตั้งค่าอื่น ๆ
    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  }
  // ...การตั้งค่าอื่น ๆ
);

คุณอาจสังเกตได้ว่า ขอบเขต (scopes) ถูกกำหนดแยกจาก ทรัพยากร API (API resources) นี่เป็นเพราะ Resource Indicators for OAuth 2.0 ระบุว่า ขอบเขตสุดท้ายสำหรับคำขอจะเป็นผลคูณคาร์ทีเซียนของขอบเขตทั้งหมดในบริการเป้าหมายทั้งหมด

ดังนั้น ในกรณีข้างต้น ขอบเขต (scopes) สามารถทำให้เรียบง่ายขึ้นจากการกำหนดใน Logto โดยทั้งสอง ทรัพยากร API (API resources) สามารถมีขอบเขต read และ write ได้โดยไม่ต้องมีคำนำหน้า จากนั้น ในการตั้งค่า Logto:

hooks.server.ts

export const handle = handleLogto(
  {
    // ...การตั้งค่าอื่น ๆ
    scopes: ['read', 'write'], // ขอบเขต (scopes)
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // ทรัพยากร API (resources)
  }
  // ...การตั้งค่าอื่น ๆ
);

สำหรับแต่ละ ทรัพยากร API (API resource) จะร้องขอทั้งขอบเขต read และ write

บันทึก:

คุณสามารถร้องขอขอบเขต (scopes) ที่ไม่ได้กำหนดไว้ใน ทรัพยากร API (API resources) ได้ เช่น คุณสามารถร้องขอขอบเขต email ได้ แม้ว่า ทรัพยากร API (API resources) จะไม่มีขอบเขต email ให้ ขอบเขตที่ไม่มีจะถูกละเว้นอย่างปลอดภัย

หลังจากลงชื่อเข้าใช้สำเร็จ Logto จะออกขอบเขตที่เหมาะสมให้กับ ทรัพยากร API (API resources) ตามบทบาทของผู้ใช้

ดึงโทเค็นการเข้าถึง (Access token) สำหรับทรัพยากร API

เพื่อดึงโทเค็นการเข้าถึง (Access token) สำหรับทรัพยากร API เฉพาะ คุณสามารถใช้เมธอด getAccessToken ได้ดังนี้:

const token = await locals.logtoClient.getAccessToken('https://shopping.your-app.com/api');

เมธอดนี้จะส่งคืนโทเค็นการเข้าถึง (JWT access token) ที่สามารถใช้เข้าถึงทรัพยากร API ได้เมื่อผู้ใช้มีสิทธิ์ที่เกี่ยวข้อง หากโทเค็นการเข้าถึงที่แคชไว้หมดอายุแล้ว เมธอดนี้จะพยายามใช้โทเค็นรีเฟรช (Refresh token) เพื่อขอโทเค็นการเข้าถึงใหม่โดยอัตโนมัติ

ดึงโทเค็นองค์กร (Organization tokens)

หากคุณยังไม่คุ้นเคยกับ องค์กร (Organization) โปรดอ่าน 🏢 องค์กร (หลายผู้เช่า; Multi-tenancy) เพื่อเริ่มต้น

คุณต้องเพิ่ม UserScope.Organizations ขอบเขต (scope) ขณะตั้งค่า Logto client:

hooks.server.ts

import { handleLogto, UserScope } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    // ...การตั้งค่าอื่น ๆ
    scopes: [UserScope.Organizations], // ขอบเขต (scopes) ที่ร้องขอ ได้แก่ องค์กร (Organizations)
  }
  // ...การตั้งค่าอื่น ๆ
);

เมื่อผู้ใช้ลงชื่อเข้าใช้แล้ว คุณสามารถดึงโทเค็นองค์กร (organization token) สำหรับผู้ใช้ได้:

const token = await locals.logtoClient.getOrganizationToken(organizationId);

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

กระบวนการสำหรับผู้ใช้ปลายทาง: กระบวนการยืนยันตัวตน, กระบวนการบัญชี, และกระบวนการองค์กร ตั้งค่าตัวเชื่อมต่อ การอนุญาต (Authorization)