Autenticazione e autorizzazione

Questa sezione illustra i concetti di autenticazione e autorizzazione in relazione all'implementazione di Fleet Engine. Descrive le procedure da eseguire per proteggere le chiamate alle funzioni di Fleet Engine.

Puoi configurare le funzionalità fornite da Last Mile Fleet Solution tramite la console Google Cloud. Queste API e questi SDK richiedono l'utilizzo di token JWT (JSON Web Tokens) firmati utilizzando account di servizio creati dalla console Cloud.

Panoramica

Come parte del suo meccanismo di autorizzazione, Fleet Engine fornisce ulteriore sicurezza dalle chiamate provenienti da ambienti a bassa attendibilità. Gli ambienti con scarsa affidabilità includono smartphone e browser. Inoltre, Fleet Engine utilizza il principio del privilegio minimo, in base al quale a una chiamata devono essere assegnati solo i privilegi necessari per completare l'attività.

Per salvaguardare le chiamate alle funzioni provenienti da ambienti poco attendibili, Google ha progettato un meccanismo in cui il codice crea un token sul server di backend, che è un ambiente completamente attendibile. Ogni chiamata trasporta una descrizione completa della sicurezza, che viene quindi criptata in un JWT che passi con la chiamata da qualsiasi ambiente.

Principi di progettazione dell'autenticazione

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

  • I ruoli IAM definiscono l'ambito delle attività consentite per il chiamante. Ad esempio, al ruolo SuperUser è consentito svolgere qualsiasi operazione, mentre al ruolo Driver non attendibile è consentito eseguire soltanto aggiornamenti della posizione minimi.

  • I ruoli IAM sono associati agli account di servizio.

  • Le attestazioni JWT limitano ulteriormente le entità su cui il chiamante può operare. Può trattarsi di attività specifiche o veicoli di consegna.

  • Le richieste inviate a Fleet Engine contengono sempre un JWT.

    • Poiché i JWT sono associati agli account di servizio, le richieste inviate a Fleet Engine vengono associate in modo implicito all'account di servizio associato al JWT.

  • Per richiedere il JWT appropriato da passare a Fleet Engine, il codice eseguito in un ambiente con affidabilità scarsa deve prima chiamare il codice in esecuzione in un ambiente completamente attendibile.

  • Fleet Engine esegue i seguenti controlli di sicurezza:

    1. I ruoli IAM associati all'account di servizio forniscono l'autorizzazione corretta al chiamante per emettere la chiamata API.

    2. Le attestazioni JWT trasmesse nella richiesta forniscono l'autorizzazione corretta per consentire al chiamante di operare sull'entità.

Flusso di autenticazione

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

  1. L'amministratore del parco risorse crea gli account di servizio.

  2. L'amministratore del parco risorse assegna ruoli IAM specifici agli account di servizio.

  3. L'amministratore del parco risorse configura il backend con gli account di servizio.

  4. L'app client richiede un JWT al backend del partner. Il richiedente può essere l'app Driver, l'app consumer o un'app di monitoraggio.

  5. Fleet Engine emette un JWT per il rispettivo account di servizio. L'app client riceve il JWT.

  6. 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:

  1. Crea un progetto Google Cloud utilizzando la console Google Cloud.
  2. 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:

RuoloDescrizione
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.
Super user Delivery di Fleet Engine

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. La nuova 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).
  • Collega i token firmati alle richieste in uscita effettuate da uno stub gRPC o da un client GAPIC.

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:

CampoDescrizione
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:

CampoDescrizione
iss L'indirizzo email del tuo account di servizio.
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 SearchTasksAPI. 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.