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à cho phép 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 được mã hoá và 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ọ.

Đối với các lệnh gọi phương thức API từ môi trường có mức độ tin cậy thấp, Công cụ của đội xe yêu cầu sử dụng Mã thông báo web JSON (JWT) do một tài khoản dịch vụ thích hợp ký. Môi trường có mức độ tin cậy thấp bao gồm đ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, đây là một môi trường hoàn toàn đáng tin cậy. JWT được ký, mã hoá và chuyển đến ứng dụng cho các lượt tương tác máy chủ tiếp theo cho đến khi hết hạn hoặc không còn hợp lệ.

Phần phụ trợ của bạn phải xác thực và uỷ quyền cho Công cụ của đội xe bằng cách sử dụng cơ chế Thông tin xác thực mặc định của ứng dụng tiêu chuẩn. Hãy nhớ sử dụng JWT do một tài khoản dịch vụ thích hợp ký. Để biết danh sách vai trò của tài khoản dịch vụ, hãy xem vai trò của tài khoản dịch vụ Fleet Engine trong phần Kiến thức cơ bản về Fleet Engine.

Ngược lại, phần phụ trợ của bạn phải xác thực và uỷ quyền cho Công cụ của đội xe bằng cách sử dụng các cơ chế Thông tin xác thực mặc định của ứng dụng tiêu chuẩn.

Không giống như khoá API, JWT có thời hạn ngắn và chỉ giới hạn các thao tác mà vai trò được phép thực hiện. Để biết thêm thông tin về JWT, hãy xem phần 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. 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 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.

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 quyền của 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ệ số chênh lệch. 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à một thời điểm trong tương lai cách thời điểm hiện tại hơn một giờ.

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": ["*"]

Xác nhận quyền sở hữu JWT của Động cơ của đội xe

Công cụ quản lý đội xe sử dụng các khiếu nại riêng tư. Việc sử dụng các tuyên bố riêng tư đảm bảo rằng chỉ những ứng dụng được uỷ quyền mới có thể truy cập vào dữ liệu của riêng chú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 quyền vehicleid hoặc thông báo xác nhận quyề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.

Fleet Engine sử dụng các thông báo xác nhận quyền sở hữu riêng 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 các API theo 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ố 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ố delivervehicleid, taskid hoặc taskids.

Bước tiếp theo