autentica e autorizza

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

Puoi configurare le funzionalità fornite dalla soluzione Last Mile Fleet tramite Google Cloud Console. Gli SDK Fleet Engine richiedono l'utilizzo di token web JSON (JWT) firmati da un account di servizio appropriato.

Panoramica

I backend dei clienti che autenticano e autorizzano Fleet Engine devono utilizzare meccanismi standard di credenziali predefinite dell'applicazione.

Fleet Engine riceve inoltre chiamate provenienti da ambienti poco attendibili come smartphone e browser. Per salvaguardare le chiavi secret degli account di servizio, adatte solo per ambienti attendibili, i backend dei clienti dovrebbero generare token JWT (JSON Web Token) firmati con dichiarazioni aggiuntive specifiche di Fleet Engine, che possono poi essere emesse in 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 sulle risorse consentite per un'entità. Ad esempio, i ruoli Amministratore possono eseguire tutte le operazioni con Credenziali predefinite dell'applicazione, mentre il ruolo Driver non attendibile* può aggiornare solo la posizione del veicolo ed è limitato all'utilizzo di JWT per l'autenticazione e l'autorizzazione.

• Per gli ambienti non attendibili, JWT limita ulteriormente le entità su cui il chiamante potrebbe operare. Possono essere attività specifiche o veicoli per la consegna.

• Il codice in esecuzione in un ambiente a bassa attendibilità deve prima richiamare 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.

1. L'amministratore del parco risorse crea degli 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 e le credenziali predefinite dell'applicazione.

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

5. Il backend del cliente firma ed 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 e leggere o modificare i dati, a seconda dei ruoli IAM assegnati durante la fase di configurazione.

Configurazione del progetto Cloud

Per configurare il progetto cloud, crea prima il progetto, quindi crea gli account di servizio.

Per creare il tuo progetto Google Cloud:

1. Creare un progetto Google Cloud utilizzando la console Google Cloud.
2. Utilizzando la dashboard delle API e dei 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, non da una persona. In genere, un account di servizio viene utilizzato per creare JWT che concedono set di autorizzazioni diversi a seconda del ruolo. Per ridurre le possibilità di comportamenti illeciti, puoi creare più account di servizio, ciascuno con il numero minimo di ruoli richiesto ().

La soluzione Last Mile Fleet utilizza i seguenti ruoli:

Ruolo	Descrizione
Utente Delivery Trusted Driver di Fleet Engine roles/fleetengine.deliveryTrustedDriver	Concede l'autorizzazione per creare e aggiornare veicoli e 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 corriere o dai server di backend.
Utente Delivery Untrusted Driver di Fleet Engine 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 Delivery Fleet Engine roles/fleetengine.deliveryConsumer	Concede l'autorizzazione per cercare attività utilizzando un ID monitoraggio e per leggere, ma non aggiornare le informazioni sulle 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 Delivery Fleet Engine roles/fleetengine.deliveryAdmin	Concede l'autorizzazione di lettura e scrittura per le risorse di pubblicazione. Le entità con questo ruolo non hanno bisogno di utilizzare JWT, ma devono utilizzare le 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 tutte le API delle attività e dei veicoli per la consegna. I token creati da un account di servizio con questo ruolo vengono in genere utilizzati dai server di backend.
Lettore parco risorse distribuzione Fleet Engine roles/fleetengine.deliveryFleetReader	Concede l'autorizzazione per leggere le attività e i veicoli per la consegna e per 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 propri 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 devono optare per la sicurezza del ruolo Utente Untrusted Driver di Fleet Engine e fare affidamento solo sull'app mobile per inviare aggiornamenti sulla posizione dei veicoli a Fleet Engine. Tutte le altre interazioni devono avere origine dai server di backend del cliente.

Gli SDK Driver e Consumer si basano su questi ruoli standard. Tuttavia, è possibile creare ruoli personalizzati che consentono di raggruppare un set arbitrario di autorizzazioni. Gli SDK Driver e Consumer mostrano messaggi di errore quando manca un'autorizzazione richiesta. Di conseguenza, consigliamo vivamente di utilizzare l'insieme standard di ruoli presentato in precedenza al posto dei ruoli personalizzati.

Creazione di un account di servizio

Puoi creare un account di servizio utilizzando la scheda IAM & Admin > Service Accounts della console Google Cloud. Dall'elenco a discesa Ruolo, seleziona Fleet Engine e assegna uno dei ruoli all'account di servizio. Indicare l'account associato a ciascun ruolo è una buona prassi. Ad esempio, assegna all'account di servizio un nome significativo.

Per praticità, se devi generare JWT 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:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Dove [e-mail] è l'email utilizzata per l'autenticazione con gcloud (gcloud auth list --format='value(account)').

Nota: questa operazione concede al beneficiario l'autorizzazione a impersonare qualsiasi account di servizio nel progetto. Per impostare autorizzazioni più granulari, segui la documentazione di IAM sulla limitazione delle associazioni dei ruoli per un account di servizio specifico.

Libreria di autenticazione di Fleet Engine

Fleet Engine utilizza JWT per limitare l'accesso alle API Fleet Engine in ambienti non attendibili. La libreria di autenticazione di Fleet Engine, disponibile su GitHub, semplifica la costruzione 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 di file di credenziali (ad esempio l'identità di un account di servizio).

Importante: ti consigliamo vivamente di utilizzare la libreria di autenticazione di Fleet Engine con tutte le implementazioni Java.

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

Quando non utilizzi la libreria di autenticazione di Fleet Engine, i JWT devono essere creati direttamente all'interno del codebase. Per questo devi avere una conoscenza approfondita dei JWT e della loro relazione con Fleet Engine. Per questo consigliamo VIVAMENTE di sfruttare la libreria di autenticazione di Fleet Engine.

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

Una sezione dell'intestazione JWT contiene i seguenti campi:

Campo	Descrizione
alg	L'algoritmo da utilizzare. "RS256".
typ	Il tipo di token. "JWT".
kid	L'ID della chiave privata dell'account di servizio. Puoi trovare questo valore nel campo "private_key_id" del file JSON dell'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:

Campo	Descrizione
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 del 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 del 1° gennaio 1970. La richiesta non va a buon fine se il timestamp è lontano da più di un'ora.
authorization	A seconda del caso d'uso, può contenere "deliveryvehicleid", "trackingid", "taskid" o "taskid".

L'estrazione di un token JWT si riferisce alla firma del token. Per istruzioni ed esempi di codice per la creazione e la firma del JWT, consulta Autorizzazione dell'account di servizio senza OAuth. Puoi quindi collegare un token creato alle chiamate gRPC o ad altri metodi utilizzati per accedere a Fleet Engine.

Attestazioni JWT

La soluzione Last Mile Fleet utilizza rivendicazioni private. L'utilizzo delle 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 corriere, il token deve contenere l'attestazione deliveryvehicleid con il valore dell'ID veicolo per la consegna del corriere. Quindi, a seconda del ruolo del conducente, i token consentono l'accesso solo per l'ID veicolo di consegna specifico e non per qualsiasi altro ID veicolo arbitrario.

La soluzione Last Mile Fleet utilizza le seguenti rivendicazioni private:

• deliveryvehicleid: da utilizzare per chiamare le API per veicolo di consegna.
• taskid: da utilizzare per chiamare le API per attività.
• taskids: da utilizzare per chiamare il numero BatchCreateTasksAPI. Questa dichiarazione deve essere in forma di array e l'array deve contenere tutti gli ID attività necessari per completare la richiesta. Non includere rivendicazioni di tipo delivervehicleid, trackingid o taskid.
• trackingid: da utilizzare per chiamare il GetTaskTrackingInfoAPI. La rivendicazione deve corrispondere all'ID monitoraggio della richiesta. Non includere rivendicazioni delivervehicleid, taskid o taskids.

Il token deve inoltre contenere la dichiarazione 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 nella dichiarazione taskids, ma deve essere l'unico elemento dell'array.

Se vuoi creare e firmare un JSON direttamente come porta token, anziché utilizzare i token di accesso OAuth 2.0, leggi le istruzioni per 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 in una chiamata HTTP consiste nell'includere un'intestazione di autorizzazione con un token di connessione il cui valore è il token, come indicato nelle note sull'autorizzazione per singoli casi d'uso di monitoraggio della spedizione o 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": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

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

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

L'esempio seguente mostra un token per un'operazione per veicolo di distribuzione dal tuo server di backend:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "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": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

L'esempio seguente mostra un token per la tua app del conducente:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "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 dell'account di servizio.
• Per i campi iss e sub, specifica l'indirizzo email del tuo account di servizio. Puoi trovare questo valore nel campo client_email del file JSON dell'account di servizio.
• Per il campo aud, specifica https://SERVICE_NAME/.
• Per il campo iat, specifica il timestamp di creazione del token, in secondi trascorsi dalle ore 00:00:00 UTC del 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 a partire dalle ore 00:00:00 UTC del 1° gennaio 1970. 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 Responsabile consegna o Consumer. In caso contrario, il dispositivo mobile o l'utente finale avrà la possibilità di modificare o visualizzare le informazioni a cui non dovrebbe avere accesso.