Soluzione dell'ultimo miglio attualmente è disponibile solo per alcuni clienti. Contatta il team di vendita per saperne di più.

Questa pagina è stata tradotta dall'API Cloud Translation.

autentica e autorizza

Questa sezione illustra i concetti di autenticazione e autorizzazione in relazione all'integrazione con Fleet Engine.

Puoi configurare le funzionalità fornite da Last Mile Fleet Solution tramite la console Google Cloud. Gli SDK Fleet Engine richiedono l'utilizzo di token JWT (JSON Web Tokens) firmati da un account di servizio appropriato.

Panoramica

I backend dei clienti che effettuano l'autenticazione e l'autorizzazione rispetto a Fleet Engine devono utilizzare i meccanismi standard delle Credenziali predefinite dell'applicazione.

Fleet Engine riceve inoltre chiamate provenienti da ambienti poco affidabili come smartphone e browser. Per salvaguardare le chiavi private degli account di servizio, adatte solo per ambienti attendibili, i backend dei clienti dovrebbero generare token JWT (JSON Web Token) firmati con attestazioni aggiuntive specifiche di Fleet Engine, che possono poi essere inviate ad ambienti non attendibili come i telefoni cellulari.

Principi di progettazione dell'autenticazione

Il flusso di autenticazione di Fleet Engine incorpora i seguenti principi di progettazione.

I ruoli IAM definiscono un insieme di autorizzazioni per le risorse consentite per un'entità. Ad esempio, i ruoli Amministratore possono fare tutto con Credenziali predefinite dell'applicazione, mentre il ruolo Driver non attendibile* può solo aggiornare la posizione del veicolo e può utilizzare JWT per l'autenticazione e l'autorizzazione.
Per ambienti non attendibili, le attestazioni JWT limitano ulteriormente le entità su cui il chiamante può operare. Può trattarsi di attività specifiche o veicoli per la consegna.
Il codice eseguito in un ambiente poco attendibile deve prima chiamare il codice in esecuzione in un ambiente attendibile per emettere un JWT.
Fleet Engine esegue i seguenti controlli di sicurezza sulle chiamate API per una risorsa:
1. L'entità chiamante dispone delle autorizzazioni appropriate (tramite l'assegnazione del ruolo) per l'azione sulla risorsa.
2. Per i ruoli non amministratore, le attestazioni JWT passate nella richiesta forniscono l'autorizzazione necessaria per la risorsa.

Flusso di autenticazione

Il seguente diagramma di sequenza mostra questi dettagli del flusso di autenticazione.

L'amministratore del parco risorse crea gli account di servizio.
L'amministratore del parco risorse assegna ruoli IAM specifici agli account di servizio.
L'amministratore del parco risorse configura il backend con gli account di servizio e le credenziali predefinite dell'applicazione.
L'app client richiede un JWT al suo backend. Il richiedente può essere l'app Driver, l'app consumer o un'app di monitoraggio.
Il backend del cliente firma e invia un JWT per il rispettivo account di servizio. L'app client riceve il token JWT.
L'app client utilizza il JWT per connettersi a Fleet Engine per leggere o modificare i dati, in base ai ruoli IAM assegnati durante la fase di configurazione.

Diagramma della sequenza di autenticazione

Configurazione del progetto Cloud

Per configurare il progetto cloud, devi prima creare il progetto e poi gli account di servizio.

Per creare il tuo progetto Google Cloud:

Crea un progetto Google Cloud utilizzando la console Google Cloud.
Con la dashboard API e servizi, abilita l'API Local Rides and Deliveries.

Account di servizio e ruoli IAM

Un account di servizio è un tipo speciale di account utilizzato da un'applicazione, anziché da una persona. In genere, un account di servizio viene utilizzato per mint JWT che concedono set di autorizzazioni diversi a seconda del ruolo. Per ridurre la possibilità di comportamenti illeciti, puoi creare più account di servizio, ciascuno con l'insieme minimo di ruoli richiesto ().

Last Mile Fleet Solution utilizza i seguenti ruoli:

Ruolo	Descrizione
Utente driver affidabile Delivery di Fleet Engine `roles/fleetengine.deliveryTrustedDriver`	Concede l'autorizzazione per creare e aggiornare i veicoli e le attività per la consegna, tra cui l'aggiornamento della posizione del veicolo per la consegna e dello stato o del risultato dell'attività. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai dispositivi mobili del conducente per le consegne o dai server di backend.
Utente driver non attendibile di Fleet Engine Delivery `roles/fleetengine.deliveryUntrustedDriver`	Concede l'autorizzazione per aggiornare la posizione del veicolo per la consegna. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai dispositivi mobili del corriere.
Utente consumer di Fleet Engine Delivery `roles/fleetengine.deliveryConsumer`	Concede l'autorizzazione per cercare attività utilizzando un ID monitoraggio e per leggere, ma non aggiornare le informazioni delle attività. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dal browser web di un consumer di distribuzione.
Amministratore Fleet Engine Delivery<> `roles/fleetengine.deliveryAdmin`	Concede l'autorizzazione di lettura e scrittura per le risorse di distribuzione. Le entità con questo ruolo non devono utilizzare JWT e devono invece usare Credenziali predefinite dell'applicazione. Le rivendicazioni JWT personalizzate vengono ignorate. Questo ruolo deve essere limitato agli ambienti attendibili (backend del cliente).
~~Super user Fleet Engine Delivery~~ (OBSOLETO) `roles/fleetengine.deliverySuperUser`	Concede l'autorizzazione a tutti i veicoli per la distribuzione e le API delle attività. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai server di backend.
Lettore Fleet Engine Delivery Fleet `roles/fleetengine.deliveryFleetReader`	Concede l'autorizzazione a leggere i veicoli e le attività per la consegna e a cercare attività utilizzando un ID monitoraggio. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dal browser web di un operatore del parco risorse di distribuzione.

Le organizzazioni che forniscono ai loro autisti addetti alle consegne dispositivi gestiti dall'IT aziendale possono sfruttare la flessibilità offerta dal ruolo Utente Trusted Driver di Fleet Engine e scegliere di integrare alcune o tutte le interazioni di Fleet Engine nell'app mobile.

Le organizzazioni che supportano i criteri Bring Your Own Device (Bring your own device, Porta il tuo dispositivo) dovrebbero optare per la sicurezza del ruolo Fleet Engine UnTrusted Driver User e affidarsi solo all'app mobile per inviare aggiornamenti della posizione del veicolo a Fleet Engine. Tutte le altre interazioni devono provenire dai server di backend del cliente.

Gli SDK Driver e Consumer sono basati su questi ruoli standard. Tuttavia, è possibile creare ruoli personalizzati che consentono di raggruppare un insieme arbitrario di autorizzazioni. Gli SDK Driver e Consumer mostreranno messaggi di errore quando manca un'autorizzazione richiesta. Di conseguenza, ti consigliamo vivamente di utilizzare l'insieme standard di ruoli descritto sopra anziché i ruoli personalizzati.

Creazione di un account di servizio

Puoi creare un account di servizio utilizzando la scheda IAM & Admin > Service Accounts nella console Google Cloud. Dall'elenco a discesa Ruolo, seleziona Fleet Engine e assegna uno dei ruoli all'account di servizio. È buona norma indicare l'account associato a ogni ruolo. Ad esempio, assegna all'account di servizio un nome significativo.

Per praticità, se hai bisogno di mint per client non attendibili, l'aggiunta di utenti al ruolo Creatore token account di servizio consente loro di generare token con gli strumenti a riga di comando gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Dove my-user@example.com è l'indirizzo email utilizzato per l'autenticazione con gcloud (gcloud auth list --format='value(account)').

Libreria di autenticazione Fleet Engine

Fleet Engine utilizza JWT per limitare l'accesso alle API Fleet Engine in ambienti non attendibili. La libreria di autenticazione Fleet Engine, disponibile su GitHub, semplifica la creazione dei JWT di Fleet Engine e li firma in modo sicuro.

La libreria offre i seguenti vantaggi:

Semplifica il processo di creazione dei token Fleet Engine.
Fornisce meccanismi di firma dei token diversi dall'utilizzo dei file di credenziali (come l'identità di un account di servizio).

Creazione di un token JWT (JSON Web Token) per l'autorizzazione

Se non utilizzi la libreria di autenticazione Fleet Engine, i JWT devono essere creati direttamente all'interno del tuo codebase. Ciò richiede una conoscenza approfondita dei JWT e della loro relazione con Fleet Engine. Ecco perché consigliamo vivamente di sfruttare la libreria di autenticazione Fleet Engine.

All'interno di Fleet Engine, i JWT forniscono un'autenticazione di breve durata e assicurano che i dispositivi possano modificare solo i veicoli o le attività per i quali sono autorizzati. I JWT contengono un'intestazione e una sezione di attestazione. La sezione dell'intestazione contiene informazioni quali la chiave privata da utilizzare (ottenuta dagli account di servizio) e l'algoritmo di crittografia. La sezione di attestazione contiene informazioni come data e ora di creazione del token, durata del token, servizi a cui il token richiede l'accesso e altre informazioni sull'autorizzazione per limitare l'accesso, ad esempio l'ID veicolo di consegna.

Una sezione di intestazione JWT contiene i seguenti campi:

Tecnico	Descrizione
alg	L'algoritmo da utilizzare. "RS256".
typ	Il tipo di token. "JWT".
bambino	L'ID della chiave privata del tuo account di servizio. Puoi trovare questo valore nel campo "private_key_id" del file JSON del tuo account di servizio. Assicurati di utilizzare una chiave di un account di servizio con il livello di autorizzazioni corretto.

Una sezione delle attestazioni JWT contiene i seguenti campi:

Tecnico	Descrizione
iss	L'indirizzo email del tuo account di servizio.
Pub/Sub.	L'indirizzo email del tuo account di servizio.
Aud	Il SERVICE_NAME del tuo account di servizio, in questo caso https://fleetengine.googleapis.com/
iat	Il timestamp di creazione del token, specificato in secondi trascorsi dalle ore 00:00:00 UTC, 1° gennaio 1970. Attendi 10 minuti per il disallineamento. Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore.
exp	Il timestamp di scadenza del token, specificato in secondi trascorsi dalle ore 00:00:00 UTC, 1° gennaio 1970. La richiesta non riesce se il timestamp supera un'ora nel futuro.
authorization	A seconda del caso d'uso, potrebbe contenere "deliveryvehicleid", "trackingid", "taskid" o "taskid".

La creazione di un token JWT implica la firma del token. Per istruzioni ed esempi di codice per creare e firmare il JWT, consulta Autorizzazione dell'account di servizio senza OAuth. Puoi quindi collegare un token coniato alle chiamate gRPC o ad altri metodi utilizzati per accedere a Fleet Engine.

Attestazioni JWT

Last Mile Fleet Solution utilizza rivendicazioni private. L'uso di rivendicazioni private garantisce che solo i clienti autorizzati possano accedere ai propri dati. Ad esempio, quando il backend emette un token web JSON per il dispositivo mobile di un conducente, questo token deve contenere la dichiarazione deliveryvehicleid con il valore dell'ID veicolo di consegna del conducente. Successivamente, a seconda del ruolo del conducente, i token consentono l'accesso solo per l'ID veicolo di distribuzione specifico e non per altri ID veicolo arbitrari.

Last Mile Fleet Solution utilizza le seguenti rivendicazioni private:

deliveryvehicleid: da utilizzare quando si chiamano le API per ciascun veicolo di consegna.
taskid: da utilizzare quando si chiamano API per attività.
taskids: da utilizzare per le chiamate a BatchCreateTasksAPI. Questa dichiarazione deve essere in formato array e l'array deve contenere tutti gli ID attività necessari per completare la richiesta. Non includere rivendicazioni delivervehicleid, trackingid o taskid.
trackingid: da utilizzare per le chiamate al GetTaskTrackingInfoAPI. La rivendicazione deve corrispondere all'ID monitoraggio nella richiesta. Non includere rivendicazioni delivervehicleid, taskid o taskids.

Il token deve contenere anche l'attestazione appropriata quando chiami le API dal tuo server di backend, ma puoi utilizzare il valore speciale di un asterisco ("*") per le attestazioni deliveryvehicleid, taskid e trackingid. Anche l'asterisco ("*") può essere utilizzato nell'attestazione taskids, ma deve essere l'unico elemento dell'array.

Se vuoi creare e firmare un JSON direttamente come portante di token, anziché utilizzare i token di accesso OAuth 2.0, leggi le istruzioni relative a Autorizzazione dell'account di servizio senza OAuth nella documentazione per gli sviluppatori di identità.

Il meccanismo per collegare il token a una chiamata gRPC dipende dal linguaggio e dal framework utilizzati per effettuare la chiamata. Il meccanismo per specificare un token per una chiamata HTTP prevede l'inclusione di un'intestazione di autorizzazione con un token di connessione il cui valore corrisponde al token, come indicato nelle note di autorizzazione per i casi d'uso individuali per il monitoraggio delle spedizioni o le prestazioni del parco risorse.

L'esempio seguente mostra un token per un'operazione per attività dal server di backend:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

L'esempio seguente mostra un token per un'operazione di creazione in batch dal tuo server di backend:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

L'esempio seguente mostra un token per un'operazione per-delivery-vehicle dal tuo server di backend:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

L'esempio seguente mostra un token per i clienti degli utenti finali:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

L'esempio seguente mostra un token per l'app Driver:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

Per il campo kid nell'intestazione, specifica l'ID della chiave privata dell'account di servizio. Puoi trovare questo valore nel campo private_key_id del file JSON del tuo account di servizio.
Per i campi iss e sub, specifica l'indirizzo email dell'account di servizio. Puoi trovare questo valore nel campo client_email del file JSON del tuo account di servizio.
Per il campo aud, specifica https://SERVICE_NAME/.
Per il campo iat, specifica il timestamp di creazione del token, espresso in secondi trascorsi dalle ore 00:00:00 UTC, il 1° gennaio 1970. Attendi 10 minuti per il disallineamento. Se il timestamp è troppo lontano nel passato o nel futuro, il server potrebbe segnalare un errore.
Per il campo exp, specifica il timestamp di scadenza del token, in secondi dal 1° gennaio 1970 (00:00:00 UTC). Il valore consigliato è iat + 3600.

Quando firmi il token da passare a un dispositivo mobile o a un utente finale, assicurati di utilizzare il file delle credenziali per il ruolo Driver di consegna o Consumatore. In caso contrario, il dispositivo mobile o l'utente finale avrà la possibilità di modificare o visualizzare informazioni a cui non dovrebbe avere accesso.