Token web JSON
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Un token web JSON (JWT) è uno standard web aperto utilizzato per autenticare
e autorizzare gli scambi di informazioni tra un client e un server. Quando un utente dell'app esegue l'accesso per la prima volta con le credenziali del ruolo appropriate, il server crea e restituisce un JWT codificato e firmato digitalmente da utilizzare con le richieste successive.
Questo processo autentica l'utente e lo autorizza ad accedere a percorsi,
servizi e risorse in base al suo ruolo account.
Fleet Engine richiede l'utilizzo di token web JSON (JWT) per le chiamate ai metodi API
da ambienti a bassa attendibilità: smartphone e browser.
Un JWT ha origine sul tuo server, viene firmato, criptato e trasmesso al client
per le successive interazioni con il server fino alla scadenza o alla perdita di validità.
Dettagli chiave
A differenza delle chiavi API, i JWT hanno una durata breve e limitano le operazioni solo a quelle che
il ruolo è autorizzato a eseguire. Per saperne di più sui JWT, consulta la pagina
JSON Web Tokens su Wikipedia. Per informazioni dettagliate sui ruoli di accesso, vedi
Ruoli del service account in questa guida.
Elementi JWT
I JWT contengono un'intestazione e una sezione delle rivendicazioni. La sezione dell'intestazione contiene
informazioni come la chiave privata ottenuta dai service account e l'algoritmo di crittografia. La sezione delle rivendicazioni contiene informazioni quali l'ora di creazione, la durata, i servizi a cui il JWT rivendica l'accesso e altre informazioni di autorizzazione per definire l'ambito dell'accesso, ad esempio l'ID del veicolo di consegna.
La tabella seguente fornisce dettagli descrittivi sui campi JWT in generale, nonché informazioni specifiche su dove trovare i valori di questi campi nel tuo progetto Google Cloud Fleet Engine.
Campi dell'intestazione JWT
Campo |
Descrizione |
alg |
L'algoritmo da utilizzare. `RS256`. |
typ |
Il tipo di token. `JWT`. |
bambino |
L'ID della chiave privata del service account. Puoi trovare questo valore nel campo
private_key_id del file JSON del service account. Assicurati di utilizzare una chiave di un service account con il livello corretto di autorizzazioni. |
Campi delle rivendicazioni JWT
Campo |
Descrizione |
iss |
L'indirizzo email del tuo service account, che si trova nel
campo client_email del file JSON del service account. |
Pub/Sub. |
L'indirizzo email del tuo service account, che si trova nel
campo client_email del file JSON del service account. |
aud |
SERVICE_NAME dell'account di servizio,
in questo caso https://fleetengine.googleapis.com/
|
iat |
Il timestamp della creazione del JWT, specificato in secondi
trascorsi dalle ore 00:00:00 del giorno UTC, January 1, 1970. Lascia 10 minuti per lo sfasamento.
Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore. |
exp |
Il timestamp di scadenza del JWT, specificato in secondi trascorsi
da 00:00:00 UTC, January 1, 1970. La richiesta non va a buon fine se
il timestamp è successivo di più di un'ora. |
autorizzazione |
A seconda del caso d'uso, può contenere deliveryvehicleid,
trackingid, taskid o taskids.
Se specifichi taskid, l'ambito di autorizzazione deve essere un array in uno
dei seguenti formati:
"taskids": ["task_id_one","task_id_two"]
o
"taskids": ["*"] |
Attestazioni JWT di Fleet Engine
Fleet Engine utilizza rivendicazioni private. L'utilizzo di rivendicazioni private garantisce che solo
i client autorizzati possano accedere ai propri dati.
Ad esempio, quando il server emette un JSON Web Token per il dispositivo mobile di un autista, deve contenere l'attestazione vehicleid o l'attestazione deliveryvehicleid con il valore dell'ID veicolo dell'autista. Poi,
a seconda del ruolo del conducente, i JWT consentono l'accesso solo per l'ID veicolo specifico
e non per qualsiasi altro ID veicolo arbitrario.
Fleet Engine utilizza le seguenti rivendicazioni private:
Viaggi on demand
-
vehicleid:
- L'SDK Driver utilizza sempre questa rivendicazione, indipendentemente dal fatto che operi su un viaggio
o su un veicolo. Il backend di Fleet Engine garantisce che il veicolo sia
associato al viaggio richiesto prima di apportare la modifica.
-
Il JWT può coprire sia le operazioni relative al veicolo sia quelle relative al viaggio, anche se non richieste, il che può semplificare l'implementazione della firma JWT.
-
tripid:
- L'SDK Consumer utilizza sempre questa rivendicazione.
-
Il JWT può coprire sia le operazioni relative al veicolo sia quelle relative al viaggio,
anche se non è necessario, il che può semplificare l'implementazione
della firma del token.
Attività pianificate
-
deliveryvehicleid
Utilizzare quando si chiamano API per veicolo di consegna.
-
taskid
Utilizza quando chiami le API per attività.
-
taskids
Utilizza quando chiami
BatchCreateTasksAPI. Questa rivendicazione deve essere in formato array
e l'array deve contenere tutti gli ID attività necessari per completare la
richiesta. Non includere dichiarazioni relative a delivervehicleid,
trackingid o taskid.
-
trackingid
Utilizzare quando si chiama il
GetTaskTrackingInfoAPI. L'affermazione deve corrispondere all'ID
di monitoraggio nella richiesta. Non includere dichiarazioni relative a delivervehicleid,
taskid o taskids.
Passaggi successivi
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-08-31 UTC.
[null,null,["Ultimo aggiornamento 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."]]
