Mã thông báo web JSON
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
JSON Web Token (JWT) là một tiêu chuẩn web mở được 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 đăng nhập có vai trò phù hợp, máy chủ sẽ tạo và trả về một JWT được mã hoá, ký bằng 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 đường, dịch vụ và tài nguyên dựa trên vai trò của họ trong 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 máy khách để 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 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 Mã thông báo web JSON trên Wikipedia. Để biết thông tin chi tiết về các vai trò truy cập, hãy xem phần Vai trò tài khoản dịch vụ trong hướng dẫn này.
Các phần tử JWT
JWT chứa một tiêu đề và một phần khai báo. 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á. Phần khai báo 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 khai báo quyền truy cập và thông tin uỷ quyền khác để giới hạn 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ả chi tiết về các trường JWT nói chung, cũng như thông tin cụ thể về vị trí bạn có thể tìm thấy các giá trị cho những 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ẻ |
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ụ. Đảm bảo bạn sử dụng khoá của một tài khoản dịch vụ có cấp độ quyền phù hợp. |
Trường khai báo 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 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 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 sai lệch 10 phút.
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 cách 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 taskid, phạm vi uỷ quyền phải là một mảng theo một trong các dạng sau:
"taskids": ["task_id_one","task_id_two"]
hoặc
"taskids": ["*"] |
Các khai báo JWT của Fleet Engine
Fleet Engine sử dụng các yêu cầu xác thực riêng tư. Việc sử dụng các khai báo 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 mình.
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 yêu cầu vehicleid hoặc yêu cầ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 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 tư sau:
Chuyến đi theo yêu cầu
-
vehicleid:
- Driver SDK luôn sử dụng yêu cầu này, cho dù đang hoạt động trên một chuyến đi hay xe. Phần phụ trợ 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ả các thao tác về 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 quy trình ký JWT.
-
tripid:
- Consumer SDK luôn sử dụng yêu cầu này.
-
JWT có thể bao gồm cả các thao tác về 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 tính năng ký mã thông báo.
Nhiệm vụ theo lịch
-
deliveryvehicleid
Sử dụng khi gọi các API theo từng xe giao hàng.
-
taskid
Sử dụng khi gọi API cho từng tác vụ.
-
taskids
Sử dụng khi gọi điện bằng BatchCreateTasksAPI. Yêu cầu này phải ở dạng mảng và mảng phải chứa tất cả mã nhận dạng nhiệm vụ cần thiết để hoàn tất yêu cầu. Đừng đưa ra các tuyên bố delivervehicleid, trackingid hoặc taskid.
-
trackingid
Sử dụng khi gọi GetTaskTrackingInfoAPI. Yêu cầu 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 đưa ra các tuyên bố delivervehicleid, taskid hoặc taskids.
Bước tiếp theo
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-31 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-31 UTC."],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]
