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

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

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

บันทึก:

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

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

• OIDC private key เมื่อเริ่มต้นอินสแตนซ์ Logto จะมีการสร้างคู่คีย์ public / private ขึ้นโดยอัตโนมัติ และลงทะเบียนไว้ใน 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. ลบคีย์ previous ที่เก่าที่สุด: Logto จะเก็บ OIDC private key สถานะ "Previous" ได้สูงสุด 1 คีย์ หากมี previous key อยู่แล้วเมื่อคีย์ staged กลายเป็น current คีย์ previous ที่เก่ากว่าจะถูกลบออก

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

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

คำเตือน:

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

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

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

แนะนำอัลกอริทึมลายเซ็น EC และ RSA ใน JWT (Introduction to EC and RSA signing algorithms in JWT)