การตั้งค่าบัญชีโดย Account API

Logto Account API คืออะไร

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

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

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

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

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

บันทึก:

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

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

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

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

ดึงโทเค็นการเข้าถึง

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

หากคุณไม่ได้ใช้ SDK อย่างเป็นทางการ คุณควรกำหนด resource ให้ว่างเปล่าสำหรับคำขอโทเค็นการเข้าถึงไปยัง /oidc/token

เข้าถึง Account API โดยใช้โทเค็นการเข้าถึง

คุณควรรวมโทเค็นการเข้าถึงในฟิลด์ Authorization ของส่วนหัว HTTP ในรูปแบบ 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>'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

ฟิลด์ตอบกลับอาจแตกต่างกันไปขึ้นอยู่กับการตั้งค่าศูนย์บัญชี

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

ข้อมูลบัญชีพื้นฐานประกอบด้วยชื่อผู้ใช้ ชื่อ รูปประจำตัว ข้อมูลที่กำหนดเอง และข้อมูลโปรไฟล์อื่น ๆ

เพื่ออัปเดต 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 (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":"..."}'

จัดการตัวระบุและข้อมูลที่ละเอียดอ่อนอื่น ๆ

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

รับ ID บันทึกการยืนยัน

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

เพื่อรับ 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":"..."}'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

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

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง กำหนดค่าตัวเชื่อมต่ออีเมล หรือ ตัวเชื่อมต่อ SMS และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต UserPermissionValidation แล้ว

ใช้ตัวอย่างอีเมล ขอรหัสยืนยันใหม่และรับ 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":"..."}}'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

เมื่อได้รับรหัสยืนยันแล้ว คุณสามารถใช้มันเพื่ออัปเดตสถานะการยืนยันของบันทึกการยืนยัน

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"}'

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

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

ส่งคำขอพร้อม ID บันทึกการยืนยัน

เมื่อส่งคำขอเพื่ออัปเดตตัวระบุของผู้ใช้ คุณต้องรวม ID บันทึกการยืนยันในส่วนหัวของคำขอด้วยฟิลด์ 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 จะส่งผลการตรวจสอบและข้อความแสดงข้อผิดพลาดโดยละเอียดหากรหัสผ่านไม่เป็นไปตามนโยบาย

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

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง กำหนดค่าตัวเชื่อมต่ออีเมล และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต 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 ในการตอบกลับ และได้รับรหัสยืนยันในอีเมล ใช้มันเพื่อยืนยันอีเมล

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 ในเนื้อหาคำขอเป็น newIdentifierVerificationRecordId

ID บันทึกการยืนยันสองรายการที่แตกต่างกัน:

คำขอนี้ต้องการ 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" พิสูจน์ความเป็นเจ้าของของอีเมลใหม่ (จากกระบวนการยืนยันรหัสข้างต้น)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

เคล็ดลับ:

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

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

เพื่อลบอีเมลของผู้ใช้ คุณสามารถใช้ 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 และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต BindNewIdentifier แล้ว

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

เพื่อเชื่อมโยงการเชื่อมต่อทางสังคมใหม่ ก่อนอื่นคุณควรขอ 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 ของ ตัวเชื่อมต่อทางสังคม
redirectUri: URI ที่จะเปลี่ยนเส้นทางหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณควรโฮสต์หน้าเว็บที่ URL นี้และจับการเรียกกลับ
state: สถานะที่จะส่งกลับหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน เป็นสตริงสุ่มที่ใช้เพื่อป้องกันการโจมตี CSRF

ในการตอบกลับ คุณจะพบ verificationRecordId เก็บไว้เพื่อใช้ในภายหลัง

หลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณจะได้รับการเรียกกลับที่ 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 คือข้อมูลที่ส่งกลับโดยตัวเชื่อมต่อทางสังคมหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณต้องแยกและรับพารามิเตอร์การค้นหาจาก redirectUri ในหน้าการเรียกกลับของคุณ และห่อหุ้มเป็น JSON เป็นค่าของฟิลด์ connectorData

สุดท้าย คุณสามารถใช้ endpoint POST /api/my-account/identities เพื่อเชื่อมโยงการเชื่อมต่อทางสังคม

ID บันทึกการยืนยันสองรายการที่แตกต่างกัน:

คำขอนี้ต้องการ 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" ระบุการเชื่อมต่อทางสังคมที่จะเชื่อมโยง (จากกระบวนการยืนยันทางสังคมข้างต้น)
  --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 ใน การตั้งค่าศูนย์บัญชี

ขั้นตอนที่ 1: เพิ่มต้นทางแอป front-end ของคุณไปยังต้นทางที่เกี่ยวข้อง

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

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

วิธีที่ Logto กำหนด RP ID:

การตั้งค่าเริ่มต้น: หากคุณใช้โดเมนเริ่มต้นของ Logto เพียงอย่างเดียว https://[tenant-id].logto.app RP ID คือ [tenant-id].logto.app
โดเมนที่กำหนดเอง: หากคุณได้กำหนดค่า โดเมนที่กำหนดเอง เช่น https://auth.example.com RP ID จะกลายเป็น auth.example.com

กำหนดค่า Related Origins:

ใช้ endpoint PATCH /api/account-center เพื่อเพิ่มต้นทางแอปพลิเคชัน front-end ของคุณ ตัวอย่างเช่น หากศูนย์บัญชีของแอปของคุณทำงานบน 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 ป้าย eTLD+1 ที่ไม่ซ้ำกันสำหรับ Related Origins eTLD+1 (โดเมนระดับบนสุดที่มีผลบังคับใช้บวกหนึ่งป้าย) คือส่วนโดเมนที่สามารถลงทะเบียนได้ ตัวอย่างเช่น:

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

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

ขั้นตอนที่ 2: ขอการลงทะเบียนใหม่

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

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

คุณจะได้รับการตอบกลับเช่น:

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

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

ใช้ @simplewebauthn/browser เป็นตัวอย่าง คุณสามารถใช้ฟังก์ชัน startRegistration เพื่อลงทะเบียน passkey ในเบราว์เซอร์ท้องถิ่น

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

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // ข้อมูลที่ส่งกลับโดยเซิร์ฟเวอร์ในขั้นตอนที่ 1
});
// บันทึกการตอบกลับเพื่อใช้ในภายหลัง

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

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

ขั้นตอนนี้ยืนยันลายเซ็นคริปโตกราฟีที่สร้างโดยตัวตรวจสอบเพื่อให้แน่ใจว่า 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: การตอบกลับจากเบราว์เซอร์ท้องถิ่นในขั้นตอนที่ 2
verificationRecordId: 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: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน Get a verification record ID
type: ประเภทของปัจจัย MFA ปัจจุบันรองรับเฉพาะ WebAuthn
newIdentifierVerificationRecordId: ID บันทึกการยืนยันที่ส่งกลับโดยเซิร์ฟเวอร์ในขั้นตอนที่ 1

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

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

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

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

id: ID ของการยืนยัน
type: ประเภทของการยืนยัน WebAuthn สำหรับ WebAuthn passkey
name: ชื่อของ passkey ฟิลด์ที่ไม่จำเป็น
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 ใน การตั้งค่าศูนย์บัญชี

ขั้นตอนที่ 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'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

{
  "secret": "..."
}

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

ใช้ secret เพื่อสร้าง QR code หรือแสดงโดยตรงให้ผู้ใช้ ผู้ใช้ควรเพิ่มมันลงในแอปยืนยันตัวตนของตนเอง (เช่น 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 ลงในแอปยืนยันตัวตนของตนเองแล้ว พวกเขาจำเป็นต้องยืนยันและผูกมันกับบัญชีของตนเอง ใช้ 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: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน Get a verification record ID
type: ต้องเป็น Totp
secret: TOTP secret ที่สร้างขึ้นในขั้นตอนที่ 1

บันทึก:

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

จัดการรหัสสำรอง

บันทึก:

อย่าลืม เปิดใช้งาน MFA และรหัสสำรอง ก่อน

บันทึก:

เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ mfa ใน การตั้งค่าศูนย์บัญชี

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

ใช้ endpoint POST /api/my-account/mfa-verifications/backup-codes/generate เพื่อสร้างชุดรหัสสำรองใหม่ 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'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

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

ก่อนที่จะผูกมัดรหัสสำรองกับบัญชีของผู้ใช้ คุณต้องแสดงให้ผู้ใช้และแนะนำให้พวกเขา:

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

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

ขั้นตอนที่ 3: ผูกมัดรหัสสำรองกับบัญชีผู้ใช้

ใช้ 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":"BackupCode","codes":["...","...","..."]}'

verification_record_id: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน Get a verification record ID
type: ต้องเป็น BackupCode
codes: อาร์เรย์ของรหัสสำรองที่สร้างขึ้นในขั้นตอนก่อนหน้า

บันทึก:

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

ดูรหัสสำรองที่มีอยู่

เพื่อดูรหัสสำรองที่มีอยู่และสถานะการใช้งานของพวกเขา ใช้ 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>'

เนื้อหาตอบกลับจะมีลักษณะดังนี้:

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

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

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

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

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

บันทึก:

ต้องการขอบเขต UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่าศูนย์บัญชีต้องตั้งค่าเป็น 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'

เพิกถอนเซสชันโดยใช้ ID เซสชัน

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

บันทึก:

ต้องการขอบเขต UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่าศูนย์บัญชีต้องตั้งค่าเป็น 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'

พารามิเตอร์การค้นหาเพิ่มเติม:

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

จัดการแอปที่ผู้ใช้อนุญาต (การให้สิทธิ์)

ใช้ API แอปที่ผู้ใช้อนุญาต (การให้สิทธิ์) เมื่อผู้ใช้ต้องการตรวจสอบและเพิกถอนแอปที่อนุญาตจากหน้าการตั้งค่าบัญชีของตนเอง

บันทึก:

API การให้สิทธิ์แอปใช้โมเดลสิทธิ์เดียวกันกับ API เซสชัน
ต้องการขอบเขต UserScope.Sessions
ฟิลด์ Sessions ในการตั้งค่าศูนย์บัญชีต้องเปิดใช้งาน:
- ReadOnly หรือ Edit เพื่อแสดงรายการการให้สิทธิ์
- Edit เพื่อเพิกถอนการให้สิทธิ์

แสดงรายการการให้สิทธิ์แอปที่ใช้งานอยู่

เพื่อแสดงรายการการให้สิทธิ์แอปที่ใช้งานอยู่ของผู้ใช้ปัจจุบัน ใช้ endpoint GET /api/my-account/grants

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

พารามิเตอร์การค้นหาเพิ่มเติม:

appType=firstParty: ส่งคืนเฉพาะการให้สิทธิ์แอป first-party
appType=thirdParty: ส่งคืนเฉพาะการให้สิทธิ์แอป third-party
ละเว้น appType: ส่งคืนการให้สิทธิ์ที่ใช้งานอยู่ทั้งหมด

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

เพิกถอนการให้สิทธิ์แอปโดยใช้ ID การให้สิทธิ์

เพื่อเพิกถอนการให้สิทธิ์แอปเฉพาะ ใช้ endpoint DELETE /api/my-account/grants/{grantId}

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

เมื่อการให้สิทธิ์ถูกเพิกถอน โทเค็นการเข้าถึงทึบและโทเค็นรีเฟรชที่ออกก่อนหน้านี้สำหรับการให้สิทธิ์นั้นจะถูกทำให้เป็นโมฆะ

Logto Account API คืออะไร​

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

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

ดึงโทเค็นการเข้าถึง​

เข้าถึง Account API โดยใช้โทเค็นการเข้าถึง​

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

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

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

จัดการตัวระบุและข้อมูลที่ละเอียดอ่อนอื่น ๆ​

รับ ID บันทึกการยืนยัน​

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

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

ส่งคำขอพร้อม ID บันทึกการยืนยัน​

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

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

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

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

เชื่อมโยงการเชื่อมต่อทางสังคมใหม่​

ลบการเชื่อมต่อทางสังคม​

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

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

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

จัดการรหัสสำรอง​

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

จัดการแอปที่ผู้ใช้อนุญาต (การให้สิทธิ์)​

Logto Account API คืออะไร

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

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

ดึงโทเค็นการเข้าถึง

เข้าถึง Account API โดยใช้โทเค็นการเข้าถึง

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

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

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

จัดการตัวระบุและข้อมูลที่ละเอียดอ่อนอื่น ๆ

รับ ID บันทึกการยืนยัน

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

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

ส่งคำขอพร้อม ID บันทึกการยืนยัน

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

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

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

จัดการโทรศัพท์

เชื่อมโยงการเชื่อมต่อทางสังคมใหม่

ลบการเชื่อมต่อทางสังคม

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

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

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

จัดการรหัสสำรอง

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

จัดการแอปที่ผู้ใช้อนุญาต (การให้สิทธิ์)