การตั้งค่าบัญชีผู้ใช้ด้วย 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>

บันทึก:

เพื่อให้แน่ใจว่าโทเค็นการเข้าถึงมีสิทธิ์ที่เหมาะสม โปรดตรวจสอบว่าคุณได้กำหนดขอบเขต (scopes) ที่เกี่ยวข้องใน 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 ที่เหมาะสมกับกรณีการใช้งานของคุณ
  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, // จัดการที่อยู่
    UserScope.Identities, // สำหรับ API ที่เกี่ยวกับอัตลักษณ์และ MFA
    UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้
  ],
};

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

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

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

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

บันทึก:

Account API เฉพาะสำหรับการตั้งค่าต่อไปนี้กำลังจะมาเร็วๆ นี้: SSO, Custom data (user), และการลบบัญชีผู้ใช้ ในระหว่างนี้ คุณสามารถใช้ Logto Management API เพื่อดำเนินการเหล่านี้ ดู การตั้งค่าบัญชีผู้ใช้ด้วย Management API สำหรับรายละเอียดเพิ่มเติม

API การจัดการ MFA (TOTP และ backup codes) กำลังอยู่ระหว่างการพัฒนาและจะใช้งานได้เมื่อเปิดใช้งาน flag isDevFeaturesEnabled เท่านั้น การจัดการ WebAuthn passkey พร้อมใช้งานเต็มรูปแบบ

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

โดยปกติ Account API จะถูกปิดใช้งาน คุณต้องใช้ Management API เพื่ออัปเดตการตั้งค่าระดับโลก

API endpoint /api/account-center ใช้สำหรับดึงและอัปเดตการตั้งค่าศูนย์บัญชี (account center) คุณสามารถใช้เพื่อเปิด / ปิด Account API และปรับแต่งฟิลด์ต่างๆ ได้

ตัวอย่างการร้องขอ:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

ฟิลด์ enabled ใช้สำหรับเปิด / ปิด Account API และฟิลด์ fields ใช้สำหรับปรับแต่งฟิลด์ต่างๆ โดยค่าที่เป็นไปได้คือ Off, Edit, ReadOnly ค่าเริ่มต้นคือ Off รายการฟิลด์ที่รองรับ:

name: ฟิลด์ชื่อ
avatar: ฟิลด์อวาตาร์
profile: ฟิลด์โปรไฟล์ รวมถึงฟิลด์ย่อย
username: ฟิลด์ชื่อผู้ใช้
email: ฟิลด์อีเมล
phone: ฟิลด์เบอร์โทรศัพท์
password: ฟิลด์รหัสผ่าน เมื่อดึงข้อมูลจะคืนค่า true หากผู้ใช้ตั้งรหัสผ่านไว้แล้ว มิฉะนั้นเป็น false
social: การเชื่อมต่อโซเชียล
mfa: ปัจจัย MFA

ดูรายละเอียด API เพิ่มเติมได้ที่ Logto Management API Reference

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

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

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

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

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

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

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

ข้อมูลบัญชีผู้ใช้พื้นฐานประกอบด้วยชื่อผู้ใช้ ชื่อ อวาตาร์ 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 (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 ต้องการการอนุญาต (Authorization) เพิ่มเติมสำหรับการดำเนินการที่เกี่ยวข้องกับตัวระบุและข้อมูลสำคัญอื่นๆ

รับ verification record id

ก่อนอื่น คุณต้องขอ verification record ID ที่มีอายุ 10 นาที (TTL) เพื่อใช้ยืนยันตัวตนผู้ใช้ก่อนอัปเดตข้อมูลสำคัญ หมายความว่าเมื่อผู้ใช้ยืนยันตัวตนสำเร็จผ่านรหัสผ่าน รหัสยืนยันอีเมล หรือรหัสยืนยัน SMS แล้ว จะมีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน เช่น ตัวระบุ ข้อมูลรับรอง การเชื่อมต่อโซเชียล และ 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": "..."
}

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

บันทึก:

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

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

ส่งคำขอพร้อม verification record id

เมื่อส่งคำขอเพื่ออัปเดตตัวระบุของผู้ใช้ คุณต้องแนบ verification record ID ใน header ของ request ด้วยฟิลด์ 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":"..."}'

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

บันทึก:

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

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>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

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

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

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

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

หากต้องการลบบัญชีโซเชียล ให้ใช้ 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: เพิ่ม origin ของแอป front-end ของคุณไปยัง related origins

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

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

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 ของคุณ เช่น หากศูนย์บัญชีของแอปรันที่ 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"]}'

ดูรายละเอียดเพิ่มเติมเกี่ยวกับ related origins ได้ที่ Related Origin Requests

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

ใช้ endpoint POST /api/verifications/web-authn/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 ขณะนี้รองรับเฉพาะ 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: รหัสของการยืนยัน
type: ประเภทของการยืนยัน WebAuthn สำหรับ WebAuthn passkey
name: ชื่อของ passkey (ไม่บังคับ)
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 ก่อน

บันทึก:

ขั้นตอนที่ 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:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

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

หลังผู้ใช้เพิ่ม secret ในแอป authenticator แล้ว ต้องยืนยันและผูกกับบัญชีผู้ใช้ โดยใช้ 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":"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 ก่อน

บันทึก:

ขั้นตอนที่ 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 เพียงอย่างเดียวได้ ผู้ใช้ต้องเปิดใช้งานปัจจัย MFA อื่นอย่างน้อยหนึ่งรายการ (เช่น 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 หากยังไม่ถูกใช้

Logto Account API คืออะไร​

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

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

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

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

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

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

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

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

รับ verification record id​

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

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

ส่งคำขอพร้อม verification record id​

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

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

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

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

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

ลบบัญชีโซเชียล​

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

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

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

จัดการ backup codes​

Logto Account API คืออะไร

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

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

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

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

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

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

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

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

รับ verification record id

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

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

ส่งคำขอพร้อม verification record id

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

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

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

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

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

ลบบัญชีโซเชียล

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

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

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

จัดการ backup codes