ข้ามไปยังเนื้อหาหลัก

โทเค็นการเข้าถึงส่วนบุคคล (Personal access token)

โทเค็นการเข้าถึงส่วนบุคคล (PATs) มอบวิธีที่ปลอดภัยให้ผู้ใช้มอบ โทเค็นการเข้าถึง (Access token) โดยไม่ต้องใช้ข้อมูลรับรองหรือการลงชื่อเข้าใช้แบบโต้ตอบ เหมาะสำหรับ CI / CD, สคริปต์ หรือแอปพลิเคชันที่ต้องเข้าถึงทรัพยากรแบบโปรแกรม

การจัดการโทเค็นการเข้าถึงส่วนบุคคล​

การใช้งานผ่าน Console​

คุณสามารถจัดการโทเค็นการเข้าถึงส่วนบุคคลได้ในหน้ารายละเอียดผู้ใช้ของ Console > การจัดการผู้ใช้ ในการ์ด "การยืนยันตัวตน (Authentication)" คุณจะเห็นรายการโทเค็นการเข้าถึงส่วนบุคคลและสร้างใหม่ได้

การใช้งานผ่าน Management API​

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

ใช้ PAT เพื่อมอบโทเค็นการเข้าถึง​

หลังจากสร้าง PAT แล้ว คุณสามารถใช้มันเพื่อมอบโทเค็นการเข้าถึงให้กับแอปพลิเคชันของคุณโดยใช้ endpoint สำหรับ token exchange

ความเทียบเท่าของโฟลว์โทเค็น:

โทเค็นการเข้าถึงที่ได้รับโดยใช้ PAT จะทำงาน เหมือนกันทุกประการ กับโทเค็นที่ได้รับผ่านโฟลว์ refresh_token มาตรฐาน ซึ่งหมายความว่า:

  • บริบทองค์กร: โทเค็นที่ได้จาก PAT รองรับสิทธิ์และขอบเขตขององค์กรเช่นเดียวกับโฟลว์ refresh token
  • โฟลว์การอนุญาต (Authorization flow): คุณสามารถใช้โทเค็นการเข้าถึงที่แลกด้วย PAT สำหรับ สิทธิ์ขององค์กร และ ทรัพยากร API ระดับองค์กร
  • การตรวจสอบโทเค็น (Token validation): ใช้ตรรกะการตรวจสอบเดียวกัน ต่างกันแค่ grant type เริ่มต้น

หากคุณทำงานกับองค์กร รูปแบบการเข้าถึงและสิทธิ์จะเหมือนกันไม่ว่าคุณจะใช้ PAT หรือ refresh token

คำขอ (Request)​

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

ก่อนใช้งาน token exchange grant คุณต้องเปิดใช้งานสำหรับแอปพลิเคชันของคุณก่อน:

  1. ไปที่ Console > Applications และเลือกแอปพลิเคชันของคุณ
  2. ในหน้าการตั้งค่าแอปพลิเคชัน ให้ค้นหาส่วน "Token exchange"
  3. เปิดสวิตช์ "Allow token exchange"

Token exchange ถูกปิดใช้งานโดยค่าเริ่มต้นเพื่อเหตุผลด้านความปลอดภัย หากคุณไม่เปิดใช้งาน คุณจะได้รับข้อผิดพลาดว่า "token exchange is not allowed for this application"

แอปพลิเคชันจะส่ง คำขอแลกเปลี่ยนโทเค็น (token exchange request) ไปยัง token endpoint ของ tenant โดยใช้ grant type พิเศษผ่าน HTTP POST พารามิเตอร์ต่อไปนี้จะถูกส่งใน entity-body ของ HTTP request โดยใช้รูปแบบ application/x-www-form-urlencoded

  1. client_id: จำเป็นต้องระบุ รหัสไคลเอนต์ของแอปพลิเคชัน
  2. grant_type: จำเป็นต้องระบุ ค่านี้ต้องเป็น urn:ietf:params:oauth:grant-type:token-exchange เพื่อระบุว่ากำลังแลกเปลี่ยนโทเค็น
  3. resource: ไม่จำเป็น ตัวบ่งชี้ทรัพยากร เช่นเดียวกับคำขอโทเค็นอื่น ๆ
  4. scope: ไม่จำเป็น ขอบเขตที่ร้องขอ เช่นเดียวกับคำขอโทเค็นอื่น ๆ
  5. subject_token: จำเป็นต้องระบุ PAT ของผู้ใช้
  6. subject_token_type: จำเป็นต้องระบุ ประเภทของโทเค็นความปลอดภัยที่ให้ใน subject_token ค่านี้ต้องเป็น urn:logto:token-type:personal_access_token

การตอบกลับ (Response)​

หากคำขอแลกเปลี่ยนโทเค็นสำเร็จ token endpoint ของ tenant จะส่งคืนโทเค็นการเข้าถึงที่แสดงตัวตนของผู้ใช้ การตอบกลับจะมีพารามิเตอร์ต่อไปนี้ใน entity-body ของ HTTP response โดยใช้รูปแบบ application/json

  1. access_token: จำเป็นต้องระบุ โทเค็นการเข้าถึงของผู้ใช้ เหมือนกับคำขอโทเค็นอื่น ๆ เช่น authorization_code หรือ refresh_token
  2. issued_token_type: จำเป็นต้องระบุ ประเภทของโทเค็นที่ออก ค่านี้ต้องเป็น urn:ietf:params:oauth:token-type:access_token
  3. token_type: จำเป็นต้องระบุ ประเภทของโทเค็น ค่านี้ต้องเป็น Bearer
  4. expires_in: จำเป็นต้องระบุ อายุของโทเค็นการเข้าถึง (หน่วยวินาที)
  5. scope: ไม่จำเป็น ขอบเขตของโทเค็นการเข้าถึง

ตัวอย่างการแลกเปลี่ยนโทเค็น​

สำหรับเว็บแอปพลิเคชันแบบดั้งเดิมหรือแอปพลิเคชันเครื่องต่อเครื่องที่มี app secret ให้ใส่ข้อมูลรับรองใน header Authorization โดยใช้ HTTP Basic authentication:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(app-id:app-secret)>

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

สำหรับ single-page application (SPA) หรือแอปพลิเคชัน native ที่ไม่มี app secret ให้ใส่ client_id ใน request body:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded

client_id=your-app-id
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

ตัวอย่างการตอบกลับที่สำเร็จ:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

จากนั้นหากคุณถอดรหัส access token ด้วย JWT decoder คุณจะได้ payload ตัวอย่างดังนี้:

{
  "jti": "VovNyqJ5_tuYac89eTbpF",
  "sub": "rkxl1ops7gs1",
  "iat": 1756908403,
  "exp": 1756912003,
  "scope": "read",
  "client_id": "your-app-id",
  "iss": "https://tenant-id.logto.app/oidc",
  "aud": "http://my-api.com"
}

โทเค็นการเข้าถึงส่วนบุคคลคืออะไร? ควรใช้เมื่อใด?

โทเค็นการเข้าถึงส่วนบุคคล, การยืนยันตัวตนเครื่องต่อเครื่อง (Machine-to-Machine authentication), และคีย์ API: ความหมายและตัวอย่างการใช้งานจริง