ปกป้องทรัพยากร API ระดับโกลบอล

ปกป้อง API ที่ใช้ทั่วทั้งผลิตภัณฑ์ของคุณด้วยการควบคุมการเข้าถึงตามบทบาท (RBAC) ใน Logto กำหนดบทบาทและสิทธิ์ระดับโกลบอลเพื่อควบคุมการเข้าถึงของผู้ใช้และไคลเอนต์ทั้งหมดในแอปพลิเคชันของคุณ

ทรัพยากร API ระดับโกลบอลคืออะไร?

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

กรณีการใช้งาน เช่น

• API สาธารณะหรือ endpoint ที่ใช้ร่วมกันในกลุ่มผู้ใช้ของคุณ
• Microservices ที่ไม่ได้ผูกกับระบบหลายผู้เช่า (multi-tenancy)
• API หลักของแอปพลิเคชัน (เช่น /api/users, /api/products) ที่ลูกค้าทุกคนใช้

Logto ช่วยให้คุณรักษาความปลอดภัย API เหล่านี้ด้วย OAuth 2.1 ร่วมกับการควบคุมการเข้าถึงตามบทบาทที่ยืดหยุ่น

วิธีการทำงานใน Logto

• ทรัพยากร API และสิทธิ์ถูกลงทะเบียนในระดับโกลบอล: แต่ละ API ที่คุณต้องการปกป้องจะถูกกำหนดด้วย resource indicator (URI) ที่ไม่ซ้ำ พร้อมชุดสิทธิ์ (scopes) ที่ควบคุมการเข้าถึง
• การเข้าถึงถูกควบคุมด้วยบทบาทระดับโกลบอล: คุณสามารถกำหนดสิทธิ์ให้กับบทบาท แล้วมอบหมายบทบาทเหล่านั้นให้กับผู้ใช้หรือไคลเอนต์
• แยกจากสิทธิ์ระดับองค์กร: ทรัพยากร API ระดับโกลบอลจะไม่มีบริบทขององค์กร อย่างไรก็ตาม สามารถใช้ร่วมกับบทบาทขององค์กรเพื่อเพิ่มชั้นบริบทเพิ่มเติมได้หากจำเป็น หากต้องการปกป้อง API ระดับองค์กร ดู ปกป้องทรัพยากร API ระดับองค์กร

ภาพรวมการใช้งาน

1. ลงทะเบียนทรัพยากร API ของคุณ และกำหนดสิทธิ์ใน Logto
2. กำหนดบทบาท พร้อมสิทธิ์ที่จำเป็นสำหรับการเข้าถึง API
3. มอบหมายบทบาท ให้กับผู้ใช้หรือไคลเอนต์
4. ใช้ OAuth 2.0 authorization flows เพื่อขอรับโทเค็นการเข้าถึงสำหรับ API (ค่าพารามิเตอร์ resource ต้องตรงกับ API identifier ที่ลงทะเบียนไว้)
5. ตรวจสอบโทเค็นการเข้าถึง ใน API ของคุณเพื่อบังคับใช้สิทธิ์

ทำความเข้าใจ resource indicator

Logto สร้างแบบจำลองทรัพยากร API ตาม RFC 8707: Resource Indicators for OAuth 2.0 โดย resource indicator คือ URI ที่ระบุ API หรือบริการเป้าหมายที่ร้องขออย่างไม่ซ้ำ

ประเด็นสำคัญ

• resource indicator ต้องเป็น absolute URI (เช่น https://api.example.com)
• ไม่มี fragment component; หลีกเลี่ยงการใช้ query string หากเป็นไปได้
• resource indicator ช่วยให้รองรับ audience-restricted token และสถาปัตยกรรม multi-API

ตัวอย่าง

• Management API: https://my-tenant.logto.app/api
• Custom global API: https://api.yourapp.com

กระบวนการอนุญาต: การยืนยันตัวตนและการรักษาความปลอดภัย API ของคุณ

กระบวนการด้านล่างนี้ใช้ได้ทั้งกรณีการยืนยันตัวตนของผู้ใช้แบบโต้ตอบ (browser / app) และกรณี backend เครื่องต่อเครื่อง (M2M)

โปรดทราบว่ากระบวนการนี้ไม่ได้รวมรายละเอียดพารามิเตอร์หรือ header ที่จำเป็นทั้งหมด แต่เน้นขั้นตอนสำคัญ อ่านต่อเพื่อดูตัวอย่างการทำงานจริง

การยืนยันตัวตนของผู้ใช้ = browser / app. M2M = บริการ backend หรือสคริปต์ที่ใช้ client credentials.

บันทึก:

พารามิเตอร์ resource ต้องตรงกับ API identifier (resource indicator) ที่คุณลงทะเบียนใน Logto

ขั้นตอนการใช้งาน

ลงทะเบียนทรัพยากร API ของคุณ

1. ไปที่ Console → API resources
2. สร้างทรัพยากร API ใหม่ (เช่น https://api.yourapp.com/org) และกำหนดสิทธิ์ (scopes) ของมัน

สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู กำหนดทรัพยากร API พร้อมสิทธิ์

ตั้งค่าบทบาทระดับโกลบอล

1. ไปที่ Console → Roles
2. สร้างบทบาทที่สอดคล้องกับสิทธิ์ของ API ของคุณ (เช่น read:products, write:products)
3. มอบหมายบทบาทเหล่านี้ให้กับผู้ใช้หรือไคลเอนต์ที่ต้องการเข้าถึง API

สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู ใช้บทบาทระดับโกลบอล

ขอรับโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอล

ก่อนเข้าถึงทรัพยากร API ระดับโกลบอล ไคลเอนต์ของคุณต้องขอรับโทเค็นการเข้าถึง Logto จะออก JSON Web Token (JWT) เป็นโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอล โดยปกติจะใช้ OAuth 2.0 authorization code flow, refresh token flow หรือ client credentials flow

Authorization code หรือ refresh token flow

SDK อย่างเป็นทางการของ Logto ทุกตัวรองรับการขอรับโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลด้วย refresh token flow ได้ทันที คุณยังสามารถใช้ไลบรารี OAuth 2.0 / OIDC client มาตรฐานเพื่อใช้งาน flow นี้ได้เช่นกัน

Logto SDK

เมื่อเริ่มต้น Logto client ให้เพิ่ม resource indicator ลงในพารามิเตอร์ resources (array) จากนั้นเพิ่มสิทธิ์ (scopes) ที่ต้องการลงในพารามิเตอร์ scopes

เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว ให้ส่ง resource indicator ในพารามิเตอร์ resource หรือพารามิเตอร์ที่มีชื่อคล้ายกันขณะร้องขอโทเค็นการเข้าถึง (เช่น เรียก getAccessToken())

สำหรับรายละเอียดของแต่ละ SDK ดูที่ เริ่มต้นอย่างรวดเร็ว

OAuth 2.0 / OIDC client library

เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณใส่พารามิเตอร์ resource และ scopes ที่ต้องการในคำขออนุญาต

ไลบรารีบางตัวอาจไม่รองรับพารามิเตอร์ resource โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่งพารามิเตอร์เพิ่มเติมในคำขออนุญาต ตรวจสอบเอกสารของไลบรารีของคุณสำหรับรายละเอียด

ตัวอย่างคำขออนุญาตแบบไม่เป็นทางการที่มีพารามิเตอร์ resource และ scope:

GET /oidc/auth?response_type=code
&client_id=your-client-id
&redirect_uri=https://your-app.com/callback
&scope=openid profile offline_access read:products write:products
&resource=https://api.your-app.com
&code_challenge=abc123
&code_challenge_method=S256
&state=xyz
HTTP/1.1
Host: your.logto.endpoint

เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว คุณจะได้รับ authorization code แลกเปลี่ยน code นี้เป็นโทเค็นการเข้าถึงโดยส่ง POST ไปยัง endpoint /oidc/token ของ Logto พร้อมพารามิเตอร์ resource ใน request body

ตัวอย่างคำขอโทเค็นแบบไม่เป็นทางการโดยใช้ grant type authorization code:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code
&code=authorization-code-received
&redirect_uri=https://your-app.com/callback
&resource=https://api.your-app.com

คุณยังสามารถใช้ grant type refresh_token เพื่อขอโทเค็นการเข้าถึงใหม่โดยไม่ต้องมีการโต้ตอบของผู้ใช้ ตราบใดที่มีพารามิเตอร์ resource ในคำขอ

ตัวอย่างคำขอโทเค็นแบบไม่เป็นทางการโดยใช้ grant type refresh token:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=refresh_token
&refresh_token=your-refresh-token
&resource=https://api.your-app.com

Client credentials flow

สำหรับกรณีเครื่องต่อเครื่อง (M2M) คุณสามารถใช้ client credentials flow เพื่อขอโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลของคุณ โดยส่ง POST ไปยัง endpoint /oidc/token ของ Logto คุณสามารถขอโทเค็นการเข้าถึงโดยใช้ client ID และ secret ของคุณ

มีสองพารามิเตอร์สำคัญที่ต้องใส่ในคำขอ:

• resource: resource indicator URI ของ API ที่คุณต้องการเข้าถึง (เช่น https://api.yourapp.com)
• scope: สิทธิ์ที่คุณต้องการร้องขอสำหรับ API (เช่น read:products write:products)

ตัวอย่างคำขอโทเค็นแบบไม่เป็นทางการโดยใช้ grant type client credentials:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com
&scope=read:products write:products

ตรวจสอบ JWT access token ใน API ของคุณ

JWT ที่ออกโดย Logto จะมีการอ้างสิทธิ์ (claims) ที่ API ของคุณสามารถใช้เพื่อบังคับใช้การอนุญาต

เมื่อ API ของคุณได้รับคำขอพร้อมโทเค็นการเข้าถึงที่ออกโดย Logto คุณควร:

• ตรวจสอบลายเซ็นของโทเค็น (โดยใช้ JWKs ของ Logto)
• ยืนยันว่าโทเค็นยังไม่หมดอายุ (exp claim)
• ตรวจสอบว่า iss (ผู้ออก) ตรงกับ endpoint Logto ของคุณ
• ตรวจสอบว่า aud (ผู้รับ) ตรงกับ API resource identifier ที่คุณลงทะเบียนไว้ (เช่น https://api.yourapp.com)
• แยก claim scope (คั่นด้วยช่องว่าง) และตรวจสอบสิทธิ์ที่จำเป็น

สำหรับคู่มือแบบทีละขั้นตอนและเฉพาะภาษา ดู วิธีตรวจสอบ access token

ตัวเลือก: จัดการเมื่อสิทธิ์ของผู้ใช้เปลี่ยนแปลง

ข้อมูล:

👷 กำลังดำเนินการ 🚧

แนวปฏิบัติที่ดีและเคล็ดลับด้านความปลอดภัย

• ตั้งชื่อสิทธิ์ให้สอดคล้องกับธุรกิจ: ใช้ชื่อที่ชัดเจนและสื่อถึงการกระทำจริง
• ตั้งอายุโทเค็นให้สั้น: ลดความเสี่ยงหากโทเค็นรั่วไหล
• จำกัด scope ที่ให้: ให้โทเค็นเฉพาะสิทธิ์ที่จำเป็นจริง ๆ
• ใช้ audience restriction: ตรวจสอบ claim aud เสมอเพื่อป้องกันการนำไปใช้ผิดวัตถุประสงค์

คำถามที่พบบ่อย

ถ้าไคลเอนต์ของฉันไม่รองรับพารามิเตอร์ resource ล่ะ?

ตั้งค่า API resource เริ่มต้นใน Logto Console โทเค็นจะใช้ audience นี้โดยอัตโนมัติเมื่อไม่มีการระบุพารามิเตอร์ resource ในคำขอโทเค็น

ทำไม API ของฉันถึงได้ 401 Unauthorized?

ตรวจสอบปัญหาทั่วไปดังต่อไปนี้:

• ลายเซ็นโทเค็น: ตรวจสอบว่า backend ของคุณดึง JWKs ที่ถูกต้องจาก Logto
• หมดอายุโทเค็น: ตรวจสอบว่าโทเค็นยังไม่หมดอายุ (exp claim)
• Audience: ตรวจสอบว่า claim aud ตรงกับ resource indicator ที่คุณลงทะเบียนไว้
• Scope ที่จำเป็น: ตรวจสอบว่าโทเค็นมีสิทธิ์ที่จำเป็นใน claim scope

จะทดสอบโดยไม่ต้องมีไคลเอนต์เต็มรูปแบบได้อย่างไร?

ใช้ personal access token เพื่อจำลองการเรียก API แบบยืนยันตัวตน วิธีนี้ช่วยให้คุณทดสอบ endpoint ของ API ได้โดยไม่ต้องพัฒนา OAuth flow ครบชุดในแอปไคลเอนต์ของคุณ

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

วิธีตรวจสอบ access token

RBAC ในทางปฏิบัติ: การใช้งานการอนุญาตที่ปลอดภัยสำหรับแอปของคุณ

ปรับแต่ง token claims RFC 8707: Resource Indicators