โทเค็นเว็บ JSON

โทเค็นเว็บ JSON (JWT) เป็นมาตรฐานเว็บแบบเปิดที่ใช้สำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์การแลกเปลี่ยนข้อมูลระหว่างไคลเอ็นต์กับเซิร์ฟเวอร์ เมื่อผู้ใช้แอปลงชื่อเข้าใช้เป็นครั้งแรกด้วยข้อมูลเข้าสู่ระบบที่มีบทบาทที่เหมาะสม เซิร์ฟเวอร์จะสร้างและแสดงผล JWT ที่เข้ารหัสและลงชื่อแบบดิจิทัลเพื่อใช้กับคำขอในภายหลัง กระบวนการนี้จะตรวจสอบสิทธิ์ผู้ใช้และให้สิทธิ์เข้าถึงเส้นทาง บริการ และทรัพยากรตามบทบาทในบัญชีของผู้ใช้

Fleet Engine กำหนดให้ใช้โทเค็นเว็บ JSON (JWT) สำหรับการเรียกใช้เมธอด API จาก สภาพแวดล้อมที่มีความน่าเชื่อถือต่ำ ได้แก่ สมาร์ทโฟนและเบราว์เซอร์

JWT จะเริ่มต้นในเซิร์ฟเวอร์ของคุณ มีการลงชื่อ เข้ารหัส และส่งไปยังไคลเอ็นต์สำหรับการโต้ตอบกับเซิร์ฟเวอร์ในภายหลังจนกว่าจะหมดอายุหรือไม่ถูกต้องอีกต่อไป

รายละเอียดสำคัญ

JWT มีอายุการใช้งานสั้นและจำกัดการดำเนินการเฉพาะการดำเนินการที่บทบาทได้รับอนุญาตให้ทำเท่านั้น ซึ่งแตกต่างจากคีย์ API ดูข้อมูลเพิ่มเติมเกี่ยวกับ JWT ได้ที่ โทเค็นเว็บ JSON ใน Wikipedia ดูรายละเอียดเกี่ยวกับบทบาทการเข้าถึงได้ที่ บทบาทบัญชีบริการในคู่มือนี้

องค์ประกอบ JWT

JWT มีส่วนหัวและส่วนการอ้างสิทธิ์ ส่วนหัวมีข้อมูล เช่น คีย์ส่วนตัวที่ได้รับจากบัญชีบริการ และอัลกอริทึมการเข้ารหัส ส่วนการอ้างสิทธิ์มีข้อมูล เช่น เวลาสร้าง JWT, Time to Live (TTL), บริการที่ JWT อ้างสิทธิ์เข้าถึง และข้อมูลการให้สิทธิ์อื่นๆ เพื่อกำหนดขอบเขตการเข้าถึง เช่น รหัสยานพาหนะสำหรับจัดส่ง

ตารางต่อไปนี้แสดงรายละเอียดคำอธิบายเกี่ยวกับฟิลด์ JWT โดยทั่วไป รวมถึงข้อมูลเฉพาะเกี่ยวกับตำแหน่งที่คุณสามารถค้นหาค่าสำหรับฟิลด์เหล่านี้ในโปรเจ็กต์ Fleet Engine Cloud

ฟิลด์ส่วนหัว JWT

ฟิลด์

คำอธิบาย

alg

อัลกอริทึมที่จะใช้ `RS256`

typ

ประเภทของโทเค็น `JWT`

kid

รหัสคีย์ส่วนตัวของบัญชีบริการ คุณสามารถค้นหาค่านี้ได้ใน private_key_id ฟิลด์ของไฟล์ JSON ของบัญชีบริการ ตรวจสอบว่าคุณใช้คีย์จากบัญชีบริการที่มีสิทธิ์เข้าถึงในระดับที่ถูกต้อง
ฟิลด์การอ้างสิทธิ์ JWT

ฟิลด์

คำอธิบาย

iss

อีเมลของบัญชีบริการ ซึ่งอยู่ในฟิลด์ client_email ของไฟล์ JSON ของบัญชีบริการ

sub

อีเมลของบัญชีบริการ ซึ่งอยู่ในฟิลด์ client_email ของไฟล์ JSON ของบัญชีบริการ

aud

SERVICE_NAME ของบัญชีบริการ ในกรณีนี้คือ https://fleetengine.googleapis.com/

iat

การประทับเวลาเมื่อสร้าง JWT ซึ่งระบุเป็นวินาที ที่ผ่านไปนับตั้งแต่ 00:00:00 UTC, January 1, 1970 เผื่อเวลาไว้ 10 นาทีสำหรับความคลาดเคลื่อน หากการประทับเวลาอยู่ในอดีตหรืออนาคตมากเกินไป เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด

exp

การประทับเวลาเมื่อ JWT หมดอายุ ซึ่งระบุเป็นวินาทีที่ผ่านไป นับตั้งแต่ 00:00:00 UTC, January 1, 1970 คำขอจะล้มเหลวหากการประทับเวลาอยู่ในอนาคตมากกว่า 1 ชั่วโมง

การให้สิทธิ์

อาจมี deliveryvehicleid, trackingid, taskid, หรือ taskids ทั้งนี้ขึ้นอยู่กับกรณีการใช้งาน

หากระบุ taskids ขอบเขตการให้สิทธิ์ต้องเป็นอาร์เรย์ในรูปแบบใดรูปแบบหนึ่งต่อไปนี้

"taskids": ["task_id_one","task_id_two"]

หรือ

"taskids": ["*"]

การอ้างสิทธิ์ JWT ของ Fleet Engine

Fleet Engine ใช้การอ้างสิทธิ์ส่วนตัว การใช้การอ้างสิทธิ์ส่วนตัวช่วยให้มั่นใจได้ว่ามีเพียงไคลเอ็นต์ที่ได้รับอนุญาตเท่านั้นที่เข้าถึงข้อมูลของตนเองได้

ตัวอย่างเช่น เมื่อเซิร์ฟเวอร์ออกโทเค็นเว็บ JSON สำหรับอุปกรณ์เคลื่อนที่ของคนขับ โทเค็นควรมีการอ้างสิทธิ์ vehicleid หรือการอ้างสิทธิ์ deliveryvehicleid ที่มีค่าเป็นรหัสยานพาหนะของคนขับรายนั้น จากนั้น JWT จะเปิดใช้การเข้าถึงเฉพาะรหัสยานพาหนะที่ระบุเท่านั้น ไม่ใช่รหัสยานพาหนะอื่นๆ ตามบทบาทของคนขับ

Fleet Engine ใช้การอ้างสิทธิ์ส่วนตัวต่อไปนี้

การเดินทางแบบออนดีมานด์

  • vehicleid:
    • Driver SDK จะใช้การอ้างสิทธิ์นี้เสมอ ไม่ว่าจะดำเนินการในการเดินทาง หรือยานพาหนะ แบ็กเอนด์ของ Fleet Engine จะตรวจสอบว่ายานพาหนะเชื่อมโยงกับการเดินทางที่ขอแล้วก่อนที่จะทำการแก้ไข
    • JWT สามารถครอบคลุมการดำเนินการทั้งยานพาหนะและการเดินทาง แม้ว่าจะไม่จำเป็นก็ตาม ซึ่งอาจทำให้การใช้งานการลงชื่อ JWT ง่ายขึ้น
  • tripid:
    • Consumer SDK จะใช้การอ้างสิทธิ์นี้เสมอ
    • JWT สามารถครอบคลุมการดำเนินการทั้งยานพาหนะและการเดินทาง แม้ว่าจะไม่จำเป็นก็ตาม ซึ่งอาจทำให้การใช้งานการลงชื่อโทเค็นง่ายขึ้น

งานที่กำหนดเวลาไว้

  • deliveryvehicleid

    ใช้เมื่อเรียก API ต่อยานพาหนะสำหรับจัดส่ง

  • taskid

    ใช้เมื่อเรียก API ต่อหนึ่งงาน

  • taskids

    ใช้เมื่อเรียก BatchCreateTasksAPI การอ้างสิทธิ์นี้ต้องอยู่ในรูปแบบอาร์เรย์ และอาร์เรย์ควรมีรหัสงานทั้งหมดที่จำเป็นต่อการดำเนินการคำขอให้เสร็จสมบูรณ์ อย่ารวมการอ้างสิทธิ์ delivervehicleid, trackingid, หรือ taskid

  • trackingid

    ใช้เมื่อเรียก GetTaskTrackingInfoAPI การอ้างสิทธิ์ต้องตรงกับรหัสติดตาม ในคำขอ อย่ารวมการอ้างสิทธิ์ delivervehicleid, taskid, หรือ taskids

ขั้นตอนถัดไป