Mã thông báo web JSON

Mã thông báo web JSON (JWT) là một tiêu chuẩn web mở được dùng để xác thực và uỷ quyền cho việc trao đổi thông tin giữa ứng dụng và máy chủ. Khi người dùng ứng dụng đăng nhập lần đầu bằng thông tin đăng nhập có vai trò thích hợp, máy chủ sẽ tạo và trả về một JWT được mã hoá, có chữ ký số để dùng cho các yêu cầu tiếp theo. Quy trình này vừa xác thực người dùng vừa cho phép họ truy cập vào các tuyến, dịch vụ và tài nguyên dựa trên vai trò của tài khoản.

Fleet Engine yêu cầu sử dụng Mã thông báo web JSON (JWT) cho các lệnh gọi phương thức API từ môi trường có độ tin cậy thấp: điện thoại thông minh và trình duyệt.

JWT bắt nguồn từ máy chủ của bạn, được ký, mã hoá và chuyển đến ứng dụng để tương tác với máy chủ sau đó cho đến khi hết hạn hoặc không còn hợp lệ.

Thông tin chi tiết quan trọng

Không giống như khoá API, JWT có thời gian tồn tại ngắn và chỉ cho phép thực hiện những thao tác mà vai trò đó được uỷ quyền. Để biết thêm thông tin về JWT, hãy xem bài viết Mã thông báo web JSON trên Wikipedia. Để biết thông tin chi tiết về vai trò truy cập, hãy xem phần Vai trò của tài khoản dịch vụ trong hướng dẫn này.

Phần tử JWT

JWT chứa một tiêu đề và một phần xác nhận quyền sở hữu. Phần tiêu đề chứa thông tin như khoá riêng tư lấy từ tài khoản dịch vụ và thuật toán mã hoá. Phần xác nhận quyền sở hữu chứa thông tin như thời gian tạo JWT, thời gian tồn tại, các dịch vụ mà JWT xác nhận quyền truy cập và thông tin uỷ quyền khác để xác định phạm vi truy cập; ví dụ: mã xe giao hàng.

Bảng sau đây cung cấp thông tin mô tả chi tiết về các trường JWT nói chung, cũng như thông tin cụ thể về nơi bạn có thể tìm thấy giá trị cho các trường này trong dự án trên đám mây Fleet Engine của bạn.

Trường tiêu đề JWT

Trường

Nội dung mô tả

alg

Thuật toán cần sử dụng. `RS256`.

typ

Loại mã thông báo. `JWT`.

trẻ em

Mã khoá riêng tư của tài khoản dịch vụ. Bạn có thể tìm thấy giá trị này trong trường private_key_id của tệp JSON tài khoản dịch vụ. Hãy nhớ sử dụng khoá của một tài khoản dịch vụ có cấp độ quyền chính xác.
Trường xác nhận quyền sở hữu JWT

Trường

Nội dung mô tả

iss

Địa chỉ email của tài khoản dịch vụ, có trong trường client_email của tệp JSON của tài khoản dịch vụ.

dự bị

Địa chỉ email của tài khoản dịch vụ, có trong trường client_email của tệp JSON của tài khoản dịch vụ.

aud

SERVICE_NAME của tài khoản dịch vụ, trong trường hợp này là https://fleetengine.googleapis.com/

iat

Dấu thời gian khi JWT được tạo, được chỉ định bằng số giây đã trôi qua kể từ 00:00:00 UTC, January 1, 1970. Cho phép độ lệch 10 phút. Nếu dấu thời gian quá xa trong quá khứ hoặc trong tương lai, thì máy chủ có thể báo lỗi.

hàm mũ

Dấu thời gian khi JWT hết hạn, được chỉ định bằng số giây đã trôi qua kể từ 00:00:00 UTC, January 1, 1970. Yêu cầu sẽ không thành công nếu dấu thời gian xảy ra quá một giờ trong tương lai.

uỷ quyền

Tuỳ thuộc vào trường hợp sử dụng, có thể chứa deliveryvehicleid, trackingid, taskid hoặc taskids.

Nếu chỉ định taskids, thì phạm vi uỷ quyền phải là một mảng ở một trong các dạng sau:

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

hoặc

"taskids": ["*"]

Xác nhận quyền sở hữu JWT của Fleet Engine

Fleet Engine sử dụng các thông báo xác nhận quyền sở hữu riêng tư. Việc sử dụng thông tin xác nhận quyền sở hữu riêng tư đảm bảo rằng chỉ những khách hàng được uỷ quyền mới có thể truy cập vào dữ liệu của riêng họ.

Ví dụ: khi máy chủ của bạn phát hành Mã thông báo web JSON cho thiết bị di động của tài xế, mã thông báo đó phải chứa thông báo xác nhận quyền sở hữu vehicleid hoặc thông báo xác nhận quyền sở hữu deliveryvehicleid có giá trị là mã nhận dạng xe của tài xế đó. Sau đó, tuỳ thuộc vào vai trò của tài xế, JWT chỉ cho phép truy cập vào mã nhận dạng xe cụ thể chứ không cho phép truy cập vào bất kỳ mã nhận dạng xe tuỳ ý nào khác.

Công cụ quản lý đội xe sử dụng các thông báo xác nhận quyền sở hữu riêng tư sau:

Chuyến đi theo yêu cầu

  • vehicleid:
    • SDK trình điều khiển luôn sử dụng thông báo xác nhận quyền sở hữu này, cho dù hoạt động trong một chuyến đi hay trên một chiếc xe. Phần phụ trợ của Fleet Engine đảm bảo rằng xe được liên kết với chuyến đi được yêu cầu trước khi thực hiện sửa đổi.
    • JWT có thể bao gồm cả hoạt động của xe và chuyến đi, ngay cả khi không bắt buộc, điều này có thể đơn giản hoá việc triển khai ký JWT.
  • tripid:
    • SDK Người tiêu dùng luôn sử dụng thông tin xác nhận quyền sở hữu này.
    • JWT có thể bao gồm cả hoạt động của xe và chuyến đi, ngay cả khi không bắt buộc, điều này có thể đơn giản hoá việc triển khai ký mã thông báo.

Nhiệm vụ đã lên lịch

  • deliveryvehicleid

    Sử dụng khi gọi API cho mỗi xe giao hàng.

  • taskid

    Sử dụng khi gọi API Tasks.

  • taskids

    Sử dụng khi gọi BatchCreateTasksAPI. Xác nhận quyền sở hữu này phải ở dạng mảng và mảng phải chứa tất cả mã tác vụ cần thiết để hoàn tất yêu cầu. Đừng thêm các tuyên bố delivervehicleid, trackingid hoặc taskid.

  • trackingid

    Sử dụng khi gọi GetTaskTrackingInfoAPI. Xác nhận quyền sở hữu phải khớp với mã theo dõi trong yêu cầu. Đừng thêm các tuyên bố delivervehicleid, taskid hoặc taskids.

Bước tiếp theo