Token web JSON

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 accede 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 dell'account.

Per le chiamate ai metodi dell'API da ambienti con un livello di attendibilità basso, Fleet Engine richiede l'utilizzo di token web JSON (JWT) firmati da un account di servizio appropriato. Gli ambienti con un livello di attendibilità basso includono smartphone e browser. Un JWT viene generato sul tuo server, che è un ambiente completamente attendibile. Il JWT viene firmato, criptato e passato al client per le interazioni successive con il server finché non scade o non è più valido.

Il backend deve autenticarsi e autorizzarsi in Fleet Engine utilizzando meccanismi di credenziali predefinite dell'applicazione standard. Assicurati di utilizzare JWT firmati da un account di servizio appropriato. Per un elenco dei ruoli degli account di servizio, consulta i ruoli degli account di servizio Fleet Engine in Nozioni di base su Fleet Engine.

Al contrario, il backend deve autenticarsi e autorizzarsi in Fleet Engine utilizzando i meccanismi standard delle credenziali predefinite dell'applicazione.

A differenza delle chiavi API, i token JWT hanno una durata breve e limitano le operazioni solo a quelle che il ruolo è autorizzato a eseguire. Per ulteriori informazioni sui token JWT, consulta JSON Web Tokens su Wikipedia. Per informazioni dettagliate sui ruoli di accesso, consulta Ruoli degli account di servizio in questa guida.

Elementi JWT

I JWT contengono un'intestazione e una sezione di claim. La sezione dell'intestazione contiene informazioni come la chiave privata ottenuta dagli account di servizio e l'algoritmo di crittografia. La sezione dei claim contiene informazioni come la data di creazione e il TTL del JWT, i servizi a cui il JWT dichiara di avere accesso e altre informazioni di autorizzazione per l'accesso a livello di ambito, 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 progetto Cloud di Fleet Engine.

Campi dell'intestazione JWT

Campo

Descrizione

alg

L'algoritmo da utilizzare. "RS256".

typ

Il tipo di token. "JWT".

bambino

L'ID chiave privata del tuo account di servizio. Puoi trovare questo valore nel private_key_id campo del file JSON dell'account di servizio. Assicurati di utilizzare una chiave di un account di servizio con il livello corretto di autorizzazioni.
Campi dei claim JWT

Campo

Descrizione

iss

L'indirizzo email del tuo account di servizio, disponibile nel client_email campo del file JSON dell'account di servizio.

Pub/Sub.

L'indirizzo email del tuo account di servizio, disponibile nel client_email campo del file JSON dell'account di servizio.

aud

Il valore SERVICE_NAME del tuo account di servizio, in questo caso https://fleetengine.googleapis.com/

iat

Il timestamp della creazione del JWT, specificato in secondi trascorsi dal 00:00:00 UTC, January 1, 1970. Attendi 10 minuti per l'eventuale sbilanciamento. Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore.

exp

Il timestamp della 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 è più di un'ora nel futuro.

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

Richieste JWT di Fleet Engine

Fleet Engine utilizza rivendicazioni private. L'utilizzo di rivendicazioni private garantisce che solo i clienti autorizzati possano accedere ai propri dati.

Ad esempio, quando il server emette un token web JSON per il dispositivo mobile di un conducente, deve contenere l'affermazione vehicleid o l'affermazione deliveryvehicleid con il valore dell'ID veicolo del conducente. 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 i seguenti diritti privati:

Viaggi on demand

  • vehicleid:
    • L'SDK Driver utilizza sempre questa rivendicazione, indipendentemente dal fatto che operi su una corsa o su un veicolo. Il backend di Fleet Engine garantisce che il veicolo sia associato alla corsa richiesta prima di apportare la modifica.
    • Il JWT può coprire sia le operazioni del veicolo sia quelle della corsa, anche se non è obbligatorio, il che può semplificare l'implementazione della firma JWT.
  • tripid:
    • L'SDK Consumer utilizza sempre questa rivendicazione.
    • Il JWT può coprire sia le operazioni del veicolo sia quelle del viaggio, anche se non è obbligatorio, il che può semplificare l'implementazione della firma del token.

Attività pianificate

  • deliveryvehicleid

    Da utilizzare quando si chiamano API per veicolo di consegna.

  • taskid

    Da utilizzare quando si chiamano API per attività.

  • taskids

    Da usare quando chiami BatchCreateTasksAPI. Questa rivendicazione deve essere in forma di array e l'array deve contenere tutti gli ID attività necessari per completare la richiesta. Non includere rivendicazioni delivervehicleid, trackingid o taskid.

  • trackingid

    Da usare quando chiami il numero GetTaskTrackingInfoAPI. La rivendicazione deve corrispondere all'ID monitoraggio nella richiesta. Non includere rivendicazioni delivervehicleid, taskid o taskids.

Passaggi successivi