Token Web JSON
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Token Web JSON (JWT) adalah standar web terbuka yang digunakan untuk mengautentikasi dan mengizinkan pertukaran informasi antara klien dan server. Saat pengguna aplikasi login pertama kali dengan kredensial peran yang sesuai, server akan membuat dan menampilkan JWT yang dienkode dan ditandatangani secara digital untuk digunakan dengan permintaan berikutnya.
Proses ini mengautentikasi pengguna dan memberi mereka otorisasi untuk mengakses rute, layanan, dan resource berdasarkan peran akun mereka.
Fleet Engine mewajibkan penggunaan Token Web JSON (JWT) untuk panggilan metode API
dari lingkungan dengan tingkat kepercayaan rendah: smartphone dan browser.
JWT berasal dari server Anda, ditandatangani, dienkripsi, dan diteruskan ke klien untuk interaksi server berikutnya hingga masa berlakunya habis atau tidak lagi valid.
Detail utama
Tidak seperti kunci API, JWT memiliki masa berlaku singkat dan membatasi operasi hanya pada operasi yang
dapat dilakukan oleh peran yang diberi otorisasi. Untuk mengetahui informasi selengkapnya tentang JWT, lihat JSON Web Tokens di Wikipedia. Untuk mengetahui detail tentang peran akses, lihat
Peran akun layanan dalam panduan ini.
Elemen JWT
JWT berisi header dan bagian klaim. Bagian header berisi
informasi seperti kunci pribadi yang diperoleh dari akun layanan, dan
algoritma enkripsi. Bagian klaim berisi informasi seperti waktu pembuatan JWT, masa aktif, layanan yang diklaim aksesnya oleh JWT, dan informasi otorisasi lainnya untuk menentukan cakupan akses; misalnya, ID kendaraan pengiriman.
Tabel berikut memberikan detail deskriptif tentang kolom JWT secara umum, serta informasi spesifik tentang tempat Anda dapat menemukan nilai untuk kolom ini di project Cloud Fleet Engine Anda.
Kolom header JWT
Kolom |
Deskripsi |
alg |
Algoritma yang akan digunakan. `RS256`. |
typ |
Jenis token. `JWT`. |
anak |
ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom
private_key_id dari file JSON akun layanan Anda. Pastikan
Anda menggunakan kunci dari akun layanan dengan tingkat izin yang benar. |
Kolom klaim JWT
Kolom |
Deskripsi |
iss |
Alamat email akun layanan Anda, yang ada di kolom
client_email pada file JSON akun layanan Anda. |
sub |
Alamat email akun layanan Anda, yang ada di kolom
client_email pada file JSON akun layanan Anda. |
aud |
SERVICE_NAME akun layanan Anda,
dalam hal ini https://fleetengine.googleapis.com/
|
iat |
Stempel waktu saat JWT dibuat, ditentukan dalam detik
yang berlalu sejak 00.00.00 UTC, January 1, 1970. Tunggu 10 menit untuk kemiringan.
Jika stempel waktu terlalu jauh di masa lalu, atau di masa mendatang, server mungkin melaporkan error. |
exp |
Stempel waktu saat JWT berakhir, ditentukan dalam detik yang berlalu sejak 00:00:00 UTC, January 1, 1970. Permintaan akan gagal jika
stempel waktunya lebih dari satu jam ke depan. |
otorisasi |
Bergantung pada kasus penggunaan, dapat berisi deliveryvehicleid,
trackingid, taskid, atau taskids.
Jika menentukan taskid, cakupan otorisasi harus berupa array dalam salah satu bentuk berikut:
"taskids": ["task_id_one","task_id_two"]
atau
"taskids": ["*"] |
Klaim JWT Fleet Engine
Fleet Engine menggunakan klaim pribadi. Menggunakan klaim pribadi memastikan bahwa hanya klien yang berwenang yang dapat mengakses data mereka sendiri.
Misalnya, saat server Anda menerbitkan JSON Web Token untuk perangkat seluler pengemudi, token tersebut harus berisi klaim vehicleid atau klaim deliveryvehicleid dengan nilai ID kendaraan pengemudi tersebut. Kemudian,
bergantung pada peran pengemudi, JWT memungkinkan akses hanya untuk ID kendaraan tertentu
dan bukan ID kendaraan arbitrer lainnya.
Fleet Engine menggunakan klaim pribadi berikut:
Perjalanan on-demand
-
vehicleid:
- Driver SDK selalu menggunakan klaim ini, baik saat beroperasi dalam perjalanan
atau kendaraan. Backend Fleet Engine memastikan bahwa kendaraan dikaitkan dengan perjalanan yang diminta sebelum melakukan modifikasi.
-
JWT dapat mencakup operasi kendaraan dan perjalanan, meskipun tidak diperlukan, yang dapat menyederhanakan penerapan penandatanganan JWT.
-
tripid:
- Consumer SDK selalu menggunakan klaim ini.
-
JWT dapat mencakup operasi kendaraan dan perjalanan,
sekalipun tidak diperlukan, yang dapat menyederhanakan penerapan
penandatanganan token.
Tugas terjadwal
-
deliveryvehicleid
Gunakan saat memanggil API per kendaraan pengiriman.
-
taskid
Digunakan saat memanggil API per tugas.
-
taskids
Gunakan saat memanggil
BatchCreateTasksAPI. Klaim ini harus dalam bentuk array,
dan array harus berisi semua ID tugas yang diperlukan untuk menyelesaikan
permintaan. Jangan sertakan klaim delivervehicleid,
trackingid, atau taskid.
-
trackingid
Gunakan saat memanggil
GetTaskTrackingInfoAPI. Klaim harus cocok dengan ID
pelacakan dalam permintaan. Jangan sertakan klaim delivervehicleid,
taskid, atau taskids.
Langkah berikutnya
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2025-09-05 UTC.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Informasi yang saya butuhkan tidak ada","missingTheInformationINeed","thumb-down"],["Terlalu rumit/langkahnya terlalu banyak","tooComplicatedTooManySteps","thumb-down"],["Sudah usang","outOfDate","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Masalah kode / contoh","samplesCodeIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-05 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."]]
