การตั้งค่าบัญชีผู้ใช้ด้วย Account API

Logto Account API คืออะไร

Logto Account API คือชุด API ที่ครอบคลุมซึ่งเปิดให้ผู้ใช้ปลายทางเข้าถึง API ได้โดยตรงโดยไม่ต้องผ่าน Management API จุดเด่นมีดังนี้:

เข้าถึงโดยตรง: Account API ให้อำนาจผู้ใช้ปลายทางในการเข้าถึงและจัดการโปรไฟล์บัญชีของตนเองโดยตรง โดยไม่ต้องผ่าน Management API
การจัดการโปรไฟล์ผู้ใช้และอัตลักษณ์: ผู้ใช้สามารถจัดการโปรไฟล์และการตั้งค่าความปลอดภัยได้อย่างเต็มที่ รวมถึงการอัปเดตข้อมูลอัตลักษณ์ เช่น อีเมล เบอร์โทรศัพท์ รหัสผ่าน และการจัดการการเชื่อมต่อโซเชียล รองรับ MFA และ SSO กำลังจะมาเร็ว ๆ นี้
การควบคุมการเข้าถึงระดับโกลบอล: ผู้ดูแลระบบมีสิทธิ์ควบคุมการเข้าถึงทั้งหมดและสามารถปรับแต่งแต่ละฟิลด์ได้
การอนุญาต (Authorization) ที่ไร้รอยต่อ: การอนุญาตง่ายกว่าที่เคย! เพียงใช้ client.getAccessToken() เพื่อรับโทเค็นการเข้าถึงทึบ (opaque access token) สำหรับ OP (Logto) และแนบไปกับ Authorization header เป็น Bearer <access_token>

ด้วย Logto Account API คุณสามารถสร้างระบบจัดการบัญชีผู้ใช้แบบกำหนดเอง เช่น หน้าโปรไฟล์ ที่ผสานรวมกับ Logto ได้อย่างสมบูรณ์

ตัวอย่างการใช้งานที่พบบ่อย เช่น:

ดึงข้อมูลโปรไฟล์ผู้ใช้
อัปเดตโปรไฟล์ผู้ใช้
อัปเดตรหัสผ่านผู้ใช้
อัปเดตอัตลักษณ์ผู้ใช้ เช่น อีเมล เบอร์โทรศัพท์ และการเชื่อมต่อโซเชียล
จัดการปัจจัย MFA (การยืนยัน)
จัดการเซสชันผู้ใช้

ดูรายละเอียด API ที่มีได้ที่ Logto Account API Reference และ Logto Verification API Reference

บันทึก:

ฟีเจอร์ดูบัญชี SSO และลบบัญชี มีให้ใช้งานผ่าน Logto Management APIs ดูรายละเอียดการใช้งานที่ การตั้งค่าบัญชีผู้ใช้ด้วย Management API

วิธีเปิดใช้งาน Account API

ไปที่ Console > Sign-in & account > Account center

Account API ถูกปิดใช้งานโดยค่าเริ่มต้น ดังนั้นการควบคุมการเข้าถึงจะถูกล็อกไว้ ให้สลับเปิด Enable Account API เพื่อเปิดใช้งาน

เมื่อเปิดใช้งานแล้ว ให้กำหนดสิทธิ์แต่ละฟิลด์สำหรับ identifiers, ข้อมูลโปรไฟล์ และการเข้าถึงโทเค็นของบุคคลที่สาม แต่ละฟิลด์รองรับ Off, ReadOnly หรือ Edit โดยค่าเริ่มต้นคือ Off

ฟิลด์ความปลอดภัย:
- ฟิลด์ประกอบด้วย: อีเมลหลัก, เบอร์โทรหลัก, อัตลักษณ์โซเชียล, รหัสผ่าน และ MFA
- ก่อนที่ผู้ใช้ปลายทางจะแก้ไขฟิลด์เหล่านี้ ต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับรหัสยืนยัน (verification record ID) ที่มีอายุ 10 นาที ดู รับรหัสยืนยัน (verification record id)
- หากต้องการใช้ WebAuthn passkey สำหรับ MFA ให้เพิ่มโดเมนแอป front-end ของคุณใน WebAuthn Related Origins เพื่อให้ account center และหน้าลงชื่อเข้าใช้สามารถแชร์ passkey ได้ ดู เชื่อมโยง WebAuthn passkey ใหม่
ฟิลด์โปรไฟล์:
- ฟิลด์ประกอบด้วย: ชื่อผู้ใช้, ชื่อ, อวาตาร์, profile (แอตทริบิวต์โปรไฟล์มาตรฐานอื่น ๆ) และ custom data
- ผู้ใช้ปลายทางสามารถแก้ไขฟิลด์เหล่านี้ได้โดยไม่ต้องยืนยันตัวตนเพิ่มเติม
Secret vault:
- สำหรับ OIDC หรือ OAuth social และ enterprise connectors, Logto secret vault จะเก็บโทเค็นการเข้าถึงและรีเฟรชของบุคคลที่สามอย่างปลอดภัยหลังการยืนยันตัวตน แอปสามารถเรียก API ภายนอก เช่น ซิงค์กิจกรรม Google Calendar ได้โดยไม่ต้องให้ผู้ใช้ลงชื่อเข้าใช้ซ้ำ การดึงโทเค็นจะพร้อมใช้งานโดยอัตโนมัติเมื่อเปิด Account API
การจัดการเซสชัน:
- เมื่อเปิดใช้งาน ผู้ใช้สามารถดูและจัดการเซสชันที่ใช้งานอยู่ รวมถึงข้อมูลอุปกรณ์และเวลาลงชื่อเข้าใช้ล่าสุด ผู้ใช้ยังสามารถเพิกถอนเซสชันเพื่อออกจากระบบจากอุปกรณ์เฉพาะได้
- ก่อนที่ผู้ใช้ปลายทางจะเข้าถึงการจัดการเซสชัน ต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับรหัสยืนยัน (verification record ID) ที่มีอายุ 10 นาที ดู รับรหัสยืนยัน (verification record id)

วิธีเข้าถึง Account API

บันทึก:

เพื่อให้แน่ใจว่า access token มีสิทธิ์ที่เหมาะสม โปรดกำหนดค่า scopes ที่เกี่ยวข้องใน Logto config ของคุณให้ถูกต้อง

ตัวอย่างเช่น สำหรับ API POST /api/my-account/primary-email คุณต้องกำหนดค่า scope email สำหรับ API POST /api/my-account/primary-phone คุณต้องกำหนดค่า scope phone

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...ตัวเลือกอื่น ๆ
  // เพิ่ม scopes ที่เหมาะสมกับกรณีใช้งานของคุณ
  scopes: [
    UserScope.Email, // สำหรับ `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // สำหรับ `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // จัดการ custom data
    UserScope.Address, // จัดการ address
    UserScope.Identities, // สำหรับ API ที่เกี่ยวข้องกับอัตลักษณ์และ MFA
    UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้
    UserScope.Sessions, // จัดการเซสชันผู้ใช้
  ],
};

ดึง access token

หลังจากตั้งค่า SDK ในแอปของคุณแล้ว คุณสามารถใช้เมธอด client.getAccessToken() เพื่อดึง access token ซึ่งเป็นโทเค็นทึบ (opaque token) ที่ใช้เข้าถึง Account API ได้

หากคุณไม่ได้ใช้ SDK อย่างเป็นทางการ ให้ตั้งค่า resource เป็นค่าว่างสำหรับ access token grant request ไปที่ /oidc/token

เข้าถึง Account API ด้วย access token

คุณควรแนบ access token ในฟิลด์ Authorization ของ HTTP headers ในรูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อเรียกใช้งาน Account API

ตัวอย่างการดึงข้อมูลบัญชีผู้ใช้:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน

ดึงข้อมูลบัญชีผู้ใช้

เพื่อดึงข้อมูลผู้ใช้ สามารถใช้ endpoint GET /api/my-account

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

ฟิลด์ใน response อาจแตกต่างกันไปตามการตั้งค่า account center

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน

ข้อมูลบัญชีผู้ใช้พื้นฐาน ได้แก่ ชื่อผู้ใช้, ชื่อ, อวาตาร์, custom data และข้อมูลโปรไฟล์อื่น ๆ

เพื่ออัปเดต username, name, avatar, และ customData ใช้ endpoint PATCH /api/my-account

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

เพื่ออัปเดตข้อมูลโปรไฟล์อื่น ๆ เช่น familyName, givenName, middleName, nickname, profile (profile page URL), website, gender, birthdate, zoneinfo, locale, และ address ใช้ endpoint PATCH /api/my-account/profile

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

จัดการ identifiers และข้อมูลสำคัญอื่น ๆ

ด้วยเหตุผลด้านความปลอดภัย Account API ต้องการการอนุญาต (Authorization) เพิ่มเติมสำหรับการดำเนินการที่เกี่ยวข้องกับ identifiers และข้อมูลสำคัญอื่น ๆ

รับรหัสยืนยัน (verification record id)

ก่อนอื่น คุณต้องขอ verification record ID ที่มีอายุ 10 นาที (TTL) เพื่อใช้ยืนยันตัวตนผู้ใช้ก่อนอัปเดตข้อมูลสำคัญ หมายความว่าเมื่อผู้ใช้ยืนยันตัวตนสำเร็จผ่านรหัสผ่าน, อีเมล หรือ SMS จะมีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน เช่น identifiers, credentials, การเชื่อมต่อโซเชียล และ MFA

เพื่อขอ verification record ID คุณสามารถ ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

ยืนยันรหัสผ่านผู้ใช้

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

ตัวอย่าง response:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

ยืนยันโดยส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

บันทึก:

หากใช้วิธีนี้ คุณต้อง ตั้งค่า email connector หรือ SMS connector และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template UserPermissionValidation แล้ว

ตัวอย่างการขอรหัสยืนยันทางอีเมลและรับ verification record ID:

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

ตัวอย่าง response:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

เมื่อได้รับรหัสยืนยันแล้ว สามารถใช้รหัสนั้นอัปเดตสถานะการยืนยันของ verification record ได้

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

หลังจากยืนยันรหัสแล้ว คุณสามารถใช้ verification record ID เพื่ออัปเดต identifier ของผู้ใช้ได้

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการยืนยันได้ที่ Security verification by Account API

ส่ง request พร้อม verification record id

เมื่อส่ง request เพื่ออัปเดต identifier ของผู้ใช้ ต้องแนบ verification record ID ใน request header ด้วยฟิลด์ logto-verification-id

อัปเดตรหัสผ่านผู้ใช้

เพื่ออัปเดตรหัสผ่านผู้ใช้ ใช้ endpoint POST /api/my-account/password

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

เคล็ดลับ:

เช่นเดียวกับรหัสผ่านที่สร้างระหว่างสมัครใช้งาน รหัสผ่านที่ตั้งผ่าน Account API ต้องเป็นไปตาม นโยบายรหัสผ่าน ที่คุณตั้งค่าไว้ใน Console > Security > Password policy Logto จะส่งผลการตรวจสอบและข้อความผิดพลาดโดยละเอียดหากรหัสผ่านไม่ผ่านนโยบาย

อัปเดตหรือเชื่อมโยงอีเมลใหม่

บันทึก:

หากใช้วิธีนี้ คุณต้อง ตั้งค่า email connector และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template BindNewIdentifier แล้ว

เพื่ออัปเดตหรือเชื่อมโยงอีเมลใหม่ ต้องพิสูจน์ความเป็นเจ้าของอีเมลนั้นก่อน

เรียก endpoint POST /api/verifications/verification-code เพื่อขอรหัสยืนยัน

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

คุณจะพบ verificationId ใน response และได้รับรหัสยืนยันทางอีเมล ใช้รหัสนี้เพื่อยืนยันอีเมล

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

หลังจากยืนยันรหัสแล้ว สามารถเรียก PATCH /api/my-account/primary-email เพื่ออัปเดตอีเมลของผู้ใช้ โดยตั้งค่า verificationId ใน request body เป็น newIdentifierVerificationRecordId

รหัสยืนยันสองชุดที่แตกต่างกัน:

request นี้ต้องใช้ verification record ID สองชุด:

logto-verification-id (header): พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งรหัสยืนยันไปยังอีเมล/โทรศัพท์เดิมของผู้ใช้
newIdentifierVerificationRecordId (body): พิสูจน์ความเป็นเจ้าของอีเมลใหม่ คือ verificationRecordId ที่ได้จาก POST /api/verifications/verification-code ข้างต้น

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # พิสูจน์ตัวตนผู้ใช้ (จากรหัสผ่านหรืออีเมล/โทรศัพท์เดิม)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" พิสูจน์ความเป็นเจ้าของอีเมลใหม่ (จาก flow รหัสยืนยันข้างต้น)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

เคล็ดลับ:

เช่นเดียวกับอีเมลที่เก็บระหว่างสมัครใช้งาน อีเมลใด ๆ ที่เชื่อมโยงผ่าน Account API ต้องผ่านการตรวจสอบ blocklist ที่คุณตั้งค่าไว้ใน Console > Security > Blocklist Logto จะปฏิเสธ request และส่ง error โดยละเอียดหากอีเมลละเมิดนโยบาย

ลบอีเมลของผู้ใช้

เพื่อลบอีเมลของผู้ใช้ ใช้ endpoint DELETE /api/my-account/primary-email

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

จัดการเบอร์โทรศัพท์

บันทึก:

หากใช้วิธีนี้ คุณต้อง ตั้งค่า SMS connector และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template BindNewIdentifier แล้ว

คล้ายกับการอัปเดตอีเมล คุณสามารถใช้ endpoint PATCH /api/my-account/primary-phone เพื่ออัปเดตหรือเชื่อมโยงเบอร์โทรใหม่ และใช้ endpoint DELETE /api/my-account/primary-phone เพื่อลบเบอร์โทรของผู้ใช้

เพื่อเชื่อมโยงโซเชียลใหม่ ต้องขอ authorization URL ก่อนด้วย POST /api/verifications/social

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId: ID ของ social connector
redirectUri: URI ที่จะ redirect หลังผู้ใช้อนุญาตแอป คุณควรโฮสต์หน้าเว็บที่ URL นี้และดัก callback
state: ค่าที่จะถูกส่งกลับหลังผู้ใช้อนุญาตแอป เป็นสตริงสุ่มเพื่อป้องกัน CSRF

ใน response จะมี verificationRecordId ให้เก็บไว้ใช้ในขั้นตอนถัดไป

หลังผู้ใช้อนุญาตแอป คุณจะได้รับ callback ที่ redirectUri พร้อมพารามิเตอร์ state จากนั้นใช้ endpoint POST /api/verifications/social/verify เพื่อตรวจสอบการเชื่อมโยงโซเชียล

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

connectorData คือข้อมูลที่ได้จาก social connector หลังผู้ใช้อนุญาตแอป คุณต้องดึง query parameters จาก redirectUri ในหน้า callback ของคุณและห่อเป็น JSON ในฟิลด์ connectorData

สุดท้าย ใช้ endpoint POST /api/my-account/identities เพื่อเชื่อมโยงโซเชียล

รหัสยืนยันสองชุดที่แตกต่างกัน:

request นี้ต้องใช้ verification record ID สองชุด:

logto-verification-id (header): พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งรหัสยืนยันไปยังอีเมล/โทรศัพท์เดิมของผู้ใช้
newIdentifierVerificationRecordId (body): ระบุอัตลักษณ์โซเชียลที่จะเชื่อมโยง คือ verificationRecordId ที่ได้จาก POST /api/verifications/social ข้างต้น

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # พิสูจน์ตัวตนผู้ใช้ (จากรหัสผ่านหรืออีเมล/โทรศัพท์เดิม)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" ระบุโซเชียลที่จะเชื่อมโยง (จาก flow social verification ข้างต้น)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

เพื่อลบโซเชียลที่เชื่อมโยง ใช้ endpoint DELETE /api/my-account/identities

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

เชื่อมโยง WebAuthn passkey ใหม่

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ WebAuthn ก่อน

บันทึก:

หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: เพิ่ม origin ของแอป front-end ของคุณใน Related Origins

WebAuthn passkey จะผูกกับ hostname เฉพาะที่เรียกว่า Relying Party ID (RP ID) เฉพาะแอปที่โฮสต์บน origin ของ RP ID เท่านั้นที่สามารถลงทะเบียนหรือยืนยันตัวตนด้วย passkey เหล่านั้นได้

เนื่องจากแอป front-end ของคุณเรียก Account API จากโดเมนที่ต่างจากหน้าลงชื่อเข้าใช้ของ Logto คุณต้องตั้งค่า Related Origins เพื่ออนุญาตการดำเนินการ passkey ข้าม origin

Logto กำหนด RP ID อย่างไร:

ค่าเริ่มต้น: หากใช้โดเมนเริ่มต้นของ Logto https://[tenant-id].logto.app RP ID คือ [tenant-id].logto.app
Custom domain: หากตั้งค่า custom domain เช่น https://auth.example.com RP ID จะเป็น auth.example.com

ตั้งค่า Related Origins:

ใช้ endpoint PATCH /api/account-center เพื่อเพิ่ม origin ของแอป front-end ของคุณ เช่น ถ้า account center ของแอปรันที่ https://account.example.com:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

บันทึก:

WebAuthn รองรับได้สูงสุด 5 label eTLD+1 ที่ไม่ซ้ำกันสำหรับ Related Origins โดย eTLD+1 (effective top-level domain plus one label) คือส่วนโดเมนที่ลงทะเบียนได้ เช่น:

https://example.com, https://app.example.com, และ https://auth.example.com นับเป็น หนึ่ง label (example.com)
https://shopping.com, https://shopping.co.uk, และ https://shopping.co.jp ก็นับเป็น หนึ่ง label (shopping)
https://example.com และ https://another.com นับเป็น สอง label

หากต้องการรองรับมากกว่า 5 โดเมนที่แตกต่างกันสำหรับ Related Origins ดูรายละเอียดที่ Related Origin Requests

ขั้นตอนที่ 2: ขอ registration options ใหม่

ใช้ endpoint POST /api/verifications/web-authn/registration เพื่อขอ registration สำหรับ passkey ใหม่ Logto อนุญาตให้แต่ละบัญชีผู้ใช้ลงทะเบียน passkey ได้หลายอัน

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

response ที่ได้จะเป็น:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

ขั้นตอนที่ 3: ลงทะเบียน passkey ในเบราว์เซอร์

ตัวอย่างใช้ @simplewebauthn/browser สามารถใช้ฟังก์ชัน startRegistration เพื่อสร้าง passkey ในเบราว์เซอร์

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // ข้อมูลที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1
});
// บันทึก response ไว้ใช้ในขั้นตอนถัดไป

ขั้นตอนที่ 4: ยืนยันการลงทะเบียน passkey

ใช้ endpoint POST /api/verifications/web-authn/registration/verify เพื่อตรวจสอบการลงทะเบียน passkey

ขั้นตอนนี้จะตรวจสอบลายเซ็นดิจิทัลที่สร้างโดย authenticator เพื่อให้แน่ใจว่า passkey ถูกสร้างขึ้นอย่างถูกต้องและไม่ถูกแก้ไขระหว่างส่งข้อมูล

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload: response จากเบราว์เซอร์ในขั้นตอนที่ 2
verificationRecordId: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1

ขั้นตอนที่ 5: เชื่อมโยง passkey

สุดท้าย เชื่อมโยง passkey กับบัญชีผู้ใช้โดยใช้ endpoint POST /api/my-account/mfa-verifications

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสยืนยัน (verification record ID)
type: ประเภทของ MFA factor ปัจจุบันรองรับเฉพาะ WebAuthn
newIdentifierVerificationRecordId: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1

จัดการ WebAuthn passkey ที่มีอยู่

เพื่อจัดการ WebAuthn passkey ที่มีอยู่ ใช้ endpoint GET /api/my-account/mfa-verifications เพื่อดึง passkey ปัจจุบันและปัจจัย MFA อื่น ๆ

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id: ID ของการยืนยัน
type: ประเภทของการยืนยัน WebAuthn สำหรับ WebAuthn passkey
name: ชื่อของ passkey (optional)
agent: user agent ของ passkey

อัปเดตชื่อ passkey โดยใช้ endpoint PATCH /api/my-account/mfa-verifications/{verificationId}/name:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

ลบ passkey โดยใช้ endpoint DELETE /api/my-account/mfa-verifications/{verificationId}:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

เชื่อมโยง TOTP ใหม่

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ TOTP ก่อน

บันทึก:

หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: สร้าง TOTP secret

ใช้ endpoint POST /api/my-account/mfa-verifications/totp-secret/generate เพื่อสร้าง TOTP secret

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

ตัวอย่าง response:

{
  "secret": "..."
}

ขั้นตอนที่ 2: แสดง TOTP secret ให้ผู้ใช้

ใช้ secret นี้สร้าง QR code หรือแสดงให้ผู้ใช้โดยตรง ผู้ใช้ควรเพิ่ม secret นี้ในแอป authenticator (เช่น Google Authenticator, Microsoft Authenticator หรือ Authy)

รูปแบบ URI สำหรับ QR code คือ:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

ตัวอย่าง:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

ขั้นตอนที่ 3: ผูกปัจจัย TOTP

หลังผู้ใช้เพิ่ม secret ในแอป authenticator แล้ว ต้องยืนยันและผูกกับบัญชีผู้ใช้ ใช้ endpoint POST /api/my-account/mfa-verifications เพื่อผูกปัจจัย TOTP

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสยืนยัน (verification record ID)
type: ต้องเป็น Totp
secret: TOTP secret ที่สร้างในขั้นตอนที่ 1

บันทึก:

ผู้ใช้สามารถมีปัจจัย TOTP ได้เพียงหนึ่งชุดเท่านั้น หากมีอยู่แล้ว การเพิ่มใหม่จะได้ error 422

จัดการ backup codes

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ backup codes ก่อน

บันทึก:

หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: สร้าง backup codes ใหม่

ใช้ endpoint POST /api/my-account/mfa-verifications/backup-codes/generate เพื่อสร้าง backup codes ชุดใหม่ 10 รหัส

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

ตัวอย่าง response:

{
  "codes": ["...", "...", "..."]
}

ขั้นตอนที่ 2: แสดง backup codes ให้ผู้ใช้

ก่อนผูก backup codes กับบัญชีผู้ใช้ คุณต้องแสดงรหัสเหล่านี้ให้ผู้ใช้และแนะนำให้:

ดาวน์โหลดหรือจดรหัสเหล่านี้ทันที
เก็บไว้ในที่ปลอดภัย
เข้าใจว่ารหัสแต่ละชุดใช้ได้เพียงครั้งเดียว
ทราบว่ารหัสเหล่านี้คือทางเลือกสุดท้ายหากสูญเสียการเข้าถึง MFA หลัก

ควรแสดงรหัสในรูปแบบที่ชัดเจน ง่ายต่อการคัดลอก และอาจมีตัวเลือกให้ดาวน์โหลด (เช่น ไฟล์ข้อความหรือ PDF)

ขั้นตอนที่ 3: ผูก backup codes กับบัญชีผู้ใช้

ใช้ endpoint POST /api/my-account/mfa-verifications เพื่อผูก backup codes กับบัญชีผู้ใช้

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสยืนยัน (verification record ID)
type: ต้องเป็น BackupCode
codes: อาร์เรย์ของ backup codes ที่สร้างในขั้นตอนก่อนหน้า

บันทึก:

ผู้ใช้สามารถมี backup codes ได้เพียงชุดเดียว หากใช้หมดแล้วต้องสร้างและผูกใหม่
backup codes ไม่สามารถเป็น MFA factor เดียวได้ ผู้ใช้ต้องมี MFA factor อื่น (เช่น WebAuthn หรือ TOTP) อย่างน้อยหนึ่งรายการ
backup code แต่ละรหัสใช้ได้เพียงครั้งเดียว

ดู backup codes ที่มีอยู่

เพื่อดู backup codes ที่มีอยู่และสถานะการใช้งาน ใช้ endpoint GET /api/my-account/mfa-verifications/backup-codes:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: backup code
usedAt: เวลาที่ใช้รหัสนี้ null หากยังไม่ถูกใช้

จัดการเซสชันผู้ใช้

แสดงรายการเซสชันที่ใช้งานอยู่

เพื่อแสดงรายการเซสชันที่ใช้งานของผู้ใช้ ใช้ endpoint GET /api/my-account/sessions

บันทึก:

ต้องใช้ scope UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่า account center ต้องตั้งเป็น ReadOnly หรือ Edit

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

เพิกถอนเซสชันด้วย session ID

เพื่อเพิกถอนเซสชันเฉพาะ ใช้ endpoint DELETE /api/my-account/sessions/{sessionId}

บันทึก:

ต้องใช้ scope UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่า account center ต้องตั้งเป็น Edit

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

พารามิเตอร์ query ที่เลือกได้:

revokeGrantsTarget: ระบุเป้าหมายของ grant ที่จะเพิกถอนพร้อมกับเซสชัน ค่าที่เป็นไปได้:
- all: เพิกถอน grant ทั้งหมดที่เกี่ยวข้องกับเซสชัน
- firstParty: เพิกถอนเฉพาะ grant ของแอป first-party ที่เกี่ยวข้องกับเซสชัน (แนะนำสำหรับกรณีส่วนใหญ่ เพราะเพิกถอนการเข้าถึงเฉพาะแอปของคุณเองโดยยังคง grant ของแอป third-party ไว้ เพื่อประสบการณ์ผู้ใช้ที่ดีกว่า)
- ไม่ระบุ: พฤติกรรมเริ่มต้นจะเพิกถอน grant ที่ไม่มี scope offline_access ซึ่งโดยทั่วไปหมายถึงการเพิกถอน grant ที่ไม่ใช่ refresh token สำหรับเซสชันนั้น

Logto Account API คืออะไร​

วิธีเปิดใช้งาน Account API​

วิธีเข้าถึง Account API​

ดึง access token​

เข้าถึง Account API ด้วย access token​

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน​

ดึงข้อมูลบัญชีผู้ใช้​

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน​

จัดการ identifiers และข้อมูลสำคัญอื่น ๆ​

รับรหัสยืนยัน (verification record id)​

ยืนยันรหัสผ่านผู้ใช้​

ยืนยันโดยส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้​

ส่ง request พร้อม verification record id​

อัปเดตรหัสผ่านผู้ใช้​

อัปเดตหรือเชื่อมโยงอีเมลใหม่​

ลบอีเมลของผู้ใช้​

จัดการเบอร์โทรศัพท์​

เชื่อมโยงโซเชียลใหม่​

ลบโซเชียลที่เชื่อมโยง​

เชื่อมโยง WebAuthn passkey ใหม่​

จัดการ WebAuthn passkey ที่มีอยู่​

เชื่อมโยง TOTP ใหม่​

จัดการ backup codes​

จัดการเซสชันผู้ใช้​

Logto Account API คืออะไร

วิธีเปิดใช้งาน Account API

วิธีเข้าถึง Account API

ดึง access token

เข้าถึง Account API ด้วย access token

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน

ดึงข้อมูลบัญชีผู้ใช้

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน

จัดการ identifiers และข้อมูลสำคัญอื่น ๆ

รับรหัสยืนยัน (verification record id)

ยืนยันรหัสผ่านผู้ใช้

ยืนยันโดยส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

ส่ง request พร้อม verification record id

อัปเดตรหัสผ่านผู้ใช้

อัปเดตหรือเชื่อมโยงอีเมลใหม่

ลบอีเมลของผู้ใช้

จัดการเบอร์โทรศัพท์

เชื่อมโยงโซเชียลใหม่

ลบโซเชียลที่เชื่อมโยง

เชื่อมโยง WebAuthn passkey ใหม่

จัดการ WebAuthn passkey ที่มีอยู่

เชื่อมโยง TOTP ใหม่

จัดการ backup codes

จัดการเซสชันผู้ใช้