คีย์สำหรับลงนาม (Signing keys)

คีย์สำหรับลงนาม OIDC ของ Logto (OIDC signing keys) หรือที่เรียกว่า "OIDC private keys" และ "OIDC cookie keys" คือคีย์ที่ใช้สำหรับลงนาม JWT (โทเค็นการเข้าถึง (Access tokens) และ โทเค็น ID (ID tokens)) และคุกกี้ของเบราว์เซอร์ใน เซสชันการลงชื่อเข้าใช้ (sign-in sessions) ของ Logto คีย์เหล่านี้จะถูกสร้างขึ้นเมื่อมีการ seed ฐานข้อมูล Logto (โอเพ่นซอร์ส) หรือสร้าง tenant ใหม่ (Cloud) และสามารถจัดการได้ผ่าน CLI (โอเพ่นซอร์ส), Management API หรือ Console UI

โดยปกติ Logto จะใช้ อัลกอริทึม elliptic curve (EC) ในการสร้างลายเซ็นดิจิทัล อย่างไรก็ตาม เนื่องจากผู้ใช้มักต้องตรวจสอบลายเซ็นของ JWT และเครื่องมือรุ่นเก่าหลายตัวไม่รองรับอัลกอริทึม EC (รองรับเฉพาะ RSA) เราจึงได้เพิ่มฟีเจอร์หมุนเวียนคีย์ส่วนตัว (private key rotation) และให้ผู้ใช้เลือกอัลกอริทึมสำหรับลายเซ็น (ทั้ง RSA และ EC) เพื่อให้สามารถใช้งานร่วมกับบริการที่ใช้เครื่องมือตรวจสอบลายเซ็นรุ่นเก่าได้

บันทึก:

ตามทฤษฎีแล้ว คีย์สำหรับลงนามไม่ควรถูกเปิดเผยและไม่มีวันหมดอายุ หมายความว่าไม่จำเป็นต้องหมุนเวียนคีย์ อย่างไรก็ตาม การหมุนเวียนคีย์เป็นระยะ ๆ หลังจากช่วงเวลาหนึ่งจะช่วยเพิ่มความปลอดภัย

ทำงานอย่างไร?

• OIDC private key เมื่อเริ่มต้นอินสแตนซ์ Logto จะมีการสร้างคู่คีย์สาธารณะและคีย์ส่วนตัวโดยอัตโนมัติ และลงทะเบียนไว้ใน OIDC provider ที่อยู่เบื้องหลัง ดังนั้นเมื่อ Logto ออก JWT ใหม่ (โทเค็นการเข้าถึง หรือ โทเค็น ID) โทเค็นจะถูกลงนามด้วยคีย์ส่วนตัว ในขณะเดียวกัน แอปพลิเคชันฝั่งไคลเอนต์ที่ได้รับ JWT สามารถใช้คีย์สาธารณะที่จับคู่กันเพื่อตรวจสอบลายเซ็นของโทเค็น เพื่อให้แน่ใจว่าโทเค็นไม่ได้ถูกแก้ไขโดยบุคคลที่สาม คีย์ส่วนตัวจะถูกปกป้องบนเซิร์ฟเวอร์ Logto ส่วนคีย์สาธารณะจะเปิดเผยต่อสาธารณะตามชื่อ สามารถเข้าถึงได้ผ่านอินเทอร์เฟซ /oidc/jwks ของ OIDC endpoint สามารถระบุอัลกอริทึมของคีย์สำหรับลงนามได้ขณะสร้างคีย์ส่วนตัว โดย Logto จะใช้อัลกอริทึม EC (Elliptic Curve) เป็นค่าเริ่มต้น ผู้ดูแลระบบสามารถเปลี่ยนอัลกอริทึมเริ่มต้นเป็น RSA (Rivest-Shamir-Adleman) ได้โดยการหมุนเวียนคีย์ส่วนตัว
• OIDC cookie key เมื่อผู้ใช้เริ่มต้น flow การลงชื่อเข้าใช้หรือสมัครสมาชิก จะมีการสร้าง "OIDC session" บนเซิร์ฟเวอร์ พร้อมกับชุดคุกกี้ของเบราว์เซอร์ ด้วยคุกกี้เหล่านี้ เบราว์เซอร์สามารถร้องขอ Logto Experience API เพื่อดำเนินการต่าง ๆ ในนามของผู้ใช้ เช่น ลงชื่อเข้าใช้ สมัครสมาชิก และรีเซ็ตรหัสผ่าน อย่างไรก็ตาม แตกต่างจาก JWT คุกกี้จะถูกลงนามและตรวจสอบโดยบริการ OIDC ของ Logto เองเท่านั้น ไม่จำเป็นต้องใช้การเข้ารหัสแบบอสมมาตร (asymmetric cryptography) ดังนั้นเราจึงไม่มีคีย์สาธารณะสำหรับคีย์ที่ใช้ลงนามคุกกี้ และไม่ใช้อัลกอริทึมเข้ารหัสแบบอสมมาตร

หมุนเวียนคีย์สำหรับลงนามผ่าน Console UI

Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่วยให้คุณสร้าง OIDC private key และ cookie key ใหม่ใน tenant ของคุณได้

1. ไปที่ Console > Tenant settings > OIDC configs จากนั้นคุณสามารถจัดการทั้ง OIDC private keys และ OIDC cookie keys ได้

2. หากต้องการหมุนเวียนคีย์สำหรับลงนาม ให้คลิกปุ่ม "Rotate private keys" หรือ "Rotate cookie keys" เมื่อหมุนเวียนคีย์ส่วนตัว คุณสามารถเลือกอัลกอริทึมสำหรับลงนามได้

3. คุณจะพบตารางที่แสดงคีย์สำหรับลงนามทั้งหมดที่ใช้งานอยู่ สำหรับ OIDC private keys คุณสามารถลบคีย์ก่อนหน้าได้ แต่ไม่สามารถลบคีย์ปัจจุบันหรือคีย์ถัดไปได้ สำหรับ OIDC cookie keys คุณสามารถลบคีย์ก่อนหน้าได้ แต่ไม่สามารถลบคีย์ปัจจุบันได้

   สถานะ	คำอธิบาย
   Next	สถานะนี้ใช้สำหรับการหมุนเวียน OIDC private key แบบ staged คีย์ถูกสร้างขึ้นแล้ว แต่ Logto จะยังไม่ใช้คีย์นี้ในการลงนาม JWT ใหม่จนกว่าช่วงเวลาผ่อนผันจะสิ้นสุดและคีย์นี้จะมีผลบังคับใช้
   Current	หมายถึงคีย์นี้ถูกใช้โดย Logto ในการลงนาม JWT หรือคุกกี้ที่ออกใหม่ในขณะนี้
   Previous	หมายถึงคีย์ที่เคยถูกใช้มาก่อนแต่ถูกหมุนเวียนออกไปแล้ว JWT หรือคุกกี้ที่ลงนามด้วยคีย์นี้จะยังคงใช้ได้จนกว่าจะหมดอายุหรือคีย์ถูกลบออก

โปรดจำไว้ว่าการหมุนเวียนคีย์ประกอบด้วย 3 ขั้นตอนดังนี้:

1. สร้างคีย์สำหรับลงนามใหม่: สำหรับ OIDC private keys, Logto สามารถเตรียมคีย์ใหม่ไว้ในสถานะ "Next" ก่อน เพื่อให้แอปพลิเคชันและ API ของคุณมีเวลาทำการรีเฟรชคีย์สาธารณะจาก endpoint /oidc/jwks ก่อนที่จะใช้คีย์ใหม่ในการลงนาม
2. หมุนเวียนคีย์ปัจจุบัน: เมื่อการหมุนเวียนมีผล คีย์ "Next" จะกลายเป็น "Current" และคีย์ "Current" เดิมจะกลายเป็น "Previous" โทเค็นที่ลงนามด้วยคีย์ก่อนหน้านี้จะยังคงใช้ได้
3. ลบคีย์ก่อนหน้าที่เก่าที่สุด: Logto จะเก็บ OIDC private key ในสถานะ "Previous" ได้สูงสุดหนึ่งคีย์ หากมีคีย์ "Previous" อยู่แล้วเมื่อคีย์ staged กลายเป็น current คีย์ previous ที่เก่ากว่าจะถูกลบออก

สำหรับ Logto Cloud การหมุนเวียน OIDC private key จะมีผลหลังจากช่วงเวลาผ่อนผัน 4 ชั่วโมง ในช่วงเวลานี้ คีย์ใหม่จะถูกเตรียมและเปิดเผยผ่าน JWKS ก่อนที่ Logto จะเริ่มใช้คีย์นี้ลงนาม JWT ที่ออกใหม่ ในตาราง Console คอลัมน์ Effective at จะแสดงเวลาที่คีย์ "Next" ที่ staged จะกลายเป็น "Current"

สำหรับการติดตั้งแบบ self-hosted OSS ค่าเริ่มต้นของช่วงเวลาผ่อนผันสำหรับการหมุนเวียนคีย์ส่วนตัวคือ 0 วินาที หมายความว่าการหมุนเวียนจะเกิดขึ้นทันที หากต้องการใช้ staged rotation ให้ตั้งค่าตัวแปรแวดล้อม PRIVATE_KEY_ROTATION_GRACE_PERIOD บน Logto service หรือส่งค่า rotationGracePeriod ใน request body เมื่อเรียก Management API endpoint POST /api/configs/oidc/private-keys/rotate

คำเตือน:

หลีกเลี่ยงการหมุนเวียนคีย์สำหรับลงนามซ้ำ ๆ ก่อนที่การหมุนเวียนที่รอดำเนินการจะมีผล เว้นแต่คุณต้องการแทนที่คีย์ "Next" ที่ staged โดยตั้งใจ

การลบคีย์ "Previous" เพียงคีย์เดียวเร็วเกินไป อาจทำให้ JWT หรือคุกกี้ที่ลงนามด้วยคีย์นั้นใช้งานไม่ได้

แหล่งข้อมูลที่เกี่ยวข้อง

แนะนำอัลกอริทึมการลงนาม EC และ RSA ใน JWT