Mã thông báo web JSON

Mã thông báo web JSON (JWT) là một tiêu chuẩn web mở dùng để xác thực và uỷ quyền 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 xác thực vai trò thích hợp, máy chủ sẽ tạo và trả về một JWT đã mã hoá, được ký bằng kỹ thuật số để sử dụng với 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ò tài khoản của họ.

Công cụ của Fleet 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ó mứ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 cho các lượt tương tác tiếp theo với máy chủ cho đến khi JWT hết hạn hoặc không còn hợp lệ.

Thông tin chi tiết chính

Không giống như khoá API, JWT có thời gian tồn tại ngắn và chỉ giới hạn các thao tác mà vai trò được uỷ quyền thực hiệ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. Phần tiêu đề chứa thông tin như khoá riêng tư thu được từ tài khoản dịch vụ và thuật toán mã hoá. Mục xác nhận quyền sở hữu chứa thông tin như thời gian tạo, thời gian tồn tại của JWT, 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ã nhận dạng xe giao hàng.

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

Các 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á từ một tài khoản dịch vụ có cấp độ quyền chính xác.
Trường xác nhận JWT

Trường

Nội dung mô tả

iss

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

sub

Địa chỉ email của tài khoản dịch vụ, nằm trong trường client_email của tệp JSON 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 giây kể từ 00:00:00 UTC, January 1, 1970. Chờ 10 phút để hệ thống điều chỉnh. Nếu dấu thời gian quá xa trong quá khứ hoặc trong tương lai, máy chủ có thể báo cáo lỗi.

exp

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 là hơn 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 mã công việc, 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": ["*"]

Tuyên bố JWT của Động cơ của đội xe

Công cụ của Fleet sử dụng các tuyên bố riêng tư. Việc sử dụng các tuyên bố riêng tư đảm bảo rằng chỉ các ứng dụng được uỷ quyền mới có thể truy cập vào dữ liệu của riêng ứng dụng đó.

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 người lái xe, mã thông báo đó phải chứa thông báo xác nhận vehicleid hoặc thông báo xác nhận deliveryvehicleid có giá trị là mã nhận dạng xe của người lái xe đó. Sau đó, tuỳ thuộc vào vai trò của người lái xe, JWT chỉ cho phép truy cập vào mã nhận dạng xe cụ thể chứ không phải bất kỳ mã nhận dạng xe tuỳ ý nào khác.

Công cụ của đội xe sử dụng các tuyên bố 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 này, cho dù hoạt động trên một chuyến đi hay một xe. Phần phụ trợ của Công cụ quản lý đội xe đảm bảo rằng xe được liên kết với chuyến đi đã 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 dành cho người dùng luôn sử dụng thông báo 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.

Tác vụ đã lên lịch

  • deliveryvehicleid

    Sử dụng khi gọi API theo từng phương tiện phân phối.

  • taskid

    Sử dụng khi gọi API theo tác vụ.

  • taskids

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

  • trackingid

    Sử dụng khi gọi GetTaskTrackingInfoAPI. Thông báo xác nhận quyền sở hữu phải khớp với mã theo dõi trong yêu cầu. Không đưa vào các tuyên bố xác nhận quyền sở hữu delivervehicleid, taskid hoặc taskids.

Bước tiếp theo