Questa sezione spiega i concetti di autenticazione e autorizzazione con in termini di integrazione con Fleet Engine.
Puoi configurare le funzionalità fornite dalla soluzione Last Mile Fleet tramite la console Google Cloud. SDK Fleet Engine richiedono l'utilizzo di token web JSON (JWT) firmati da un Servizio appropriato Account.
Panoramica
I backend dei clienti che autenticano e autorizzano Fleet Engine devono utilizzare standard Predefinito applicazione Credenziali i meccanismi della ricerca di informazioni.
Fleet Engine riceve inoltre chiamate che provengono da ambienti a basso livello di attendibilità come smartphone e browser. Per salvaguardare soltanto le chiavi private degli account di servizio adatto ad ambienti affidabili, i clienti per i quali si prevede che generino token JWT (JSON Web Token) firmati con dichiarazioni aggiuntive specifiche di Fleet Engine che possono poi essere inviati 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 sono autorizzati a fare tutto con il valore predefinito dell'applicazione credenziali, mentre il ruolo di conducente non attendibile* può essere aggiornato solo posizione del veicolo e limitata all'uso di JWT per l'autenticazione autorizzazione.
Per gli ambienti non attendibili, JWT limita ulteriormente le entità che su cui il chiamante può operare. Possono essere attività specifiche o veicoli per la consegna.
Il codice in esecuzione in un ambiente con attendibilità scarsa deve prima chiamare il tuo di codice in esecuzione in un ambiente attendibile per emettere un JWT.
Fleet Engine esegue i seguenti controlli di sicurezza sulle chiamate API per risorsa:
L'entità chiamante dispone delle autorizzazioni appropriate (tramite il ruolo ) per l'azione sulla risorsa.
Per i ruoli non amministratore, le attestazioni JWT passate nella richiesta forniscono il valore 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 degli 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 backend del cliente. Il richiedente potrebbe essere l'app Driver, l'app consumer o un'app di monitoraggio.
Il backend del cliente firma ed emette un JWT per il rispettivo servizio . L'app client riceve il JWT.
L'app client utilizza il JWT per connettersi a Fleet Engine e leggere o modificare dei dati, a seconda dei ruoli IAM assegnati durante la fase di configurazione.
Configurazione del progetto Cloud
Per configurare il progetto Cloud, devi prima creare il progetto e poi creare account di servizio.
Per creare il tuo progetto Google Cloud:
- Creare un progetto Google Cloud utilizzando la console Google Cloud.
- Utilizzando la dashboard dei servizi e delle API, abilita API Local Rides and Deliveries.
Account di servizio e Ruoli IAM
Un account di servizio è un particolare tipo di account usato da un'applicazione, non da una persona. In genere, un account di servizio viene utilizzato per creare JWT che concedono degli insiemi di autorizzazioni in base al ruolo. Per ridurre la possibilità di comportamenti illeciti puoi creare più account di servizio, ognuno con l'insieme minimo di ruoli obbligatorio ().
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, compreso l'aggiornamento della posizione del veicolo per la consegna e dello stato delle attività o come risultato. Token generati da un account di servizio con questo ruolo vengono generalmente utilizzati dai dispositivi mobili del corriere o nei tuoi 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. Token coniati da un account di servizio con questo ruolo sono in genere utilizzate dalla distribuzione dispositivi mobili del conducente. |
Utente consumer Delivery Fleet Engine
roles/fleetengine.deliveryConsumer |
Concede l'autorizzazione per cercare attività utilizzando un ID monitoraggio. leggere ma non aggiornare le informazioni sulle attività. Token coniati da un account di servizio con questo ruolo sono in genere utilizzate da una distribuzione il browser web del consumatore. |
Amministratore Delivery Fleet Engine
roles/fleetengine.deliveryAdmin |
Concede l'autorizzazione di lettura e scrittura per le risorse di pubblicazione. Presidi con questo ruolo non hanno bisogno di utilizzare JWT, ma dovrebbero usare Credenziali predefinite. Le rivendicazioni JWT personalizzate vengono ignorate. Questo ruolo deve essere limitati ad ambienti attendibili (backend del cliente). |
roles/fleetengine.deliverySuperUser |
Concede l'autorizzazione a tutte le API delle attività e dei veicoli per la consegna. Token coniati da un account di servizio con questo ruolo sono in genere utilizzate dal backend server web. |
Lettore parco risorse distribuzione Fleet Engine
roles/fleetengine.deliveryFleetReader |
Concede l'autorizzazione per leggere i veicoli e le attività per la consegna e per cercare con un ID monitoraggio. Token generati da un account di servizio con questo vengono generalmente utilizzati dal browser web di un operatore del parco risorse di distribuzione. |
Organizzazioni che forniscono ai propri fattorini di dispositivi gestiti l'IT aziendale può sfruttare la flessibilità offerta da Fleet Engine il ruolo Utente Trusted Driver e scegliere di integrare alcuni o tutti i componenti di Fleet Engine interazioni nell'app mobile.
Le organizzazioni che supportano i criteri Bring Your Own Device dovrebbero optare per il del ruolo Utente Untrusted Driver di Fleet Engine e fare affidamento solo app mobile per inviare aggiornamenti sulla posizione dei veicoli a Fleet Engine. Tutti gli altri le 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 insieme arbitrario di autorizzazioni. Gli SDK Driver e Consumer mostrano messaggi di errore quando autorizzazione richiesta mancante. Di conseguenza, consigliamo vivamente utilizzando 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 IAM & Admin > Service Accounts
nella console Google Cloud. Dall'elenco a discesa Ruolo, selezionare
Fleet Engine e assegnare uno dei ruoli all'account di servizio. Molto bene
l'account associato a ciascun ruolo.
Ad esempio, assegna all'account di servizio un nome significativo.
Per praticità, se devi creare JWT per client non attendibili, aggiungi agli 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
autenticarsi con gcloud (gcloud auth list
--format='value(account)'
).
Libreria di autenticazione di Fleet Engine
Fleet Engine utilizza JWT per limitare l'accesso alle API di Fleet Engine nei campi non attendibili ambienti cloud-native. La libreria di autenticazione Fleet Engine, disponibile su GitHub, semplifica 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 si spaccia per un account di servizio).
Creazione di un token web JSON (JWT) per l'autorizzazione
Quando non si utilizza la libreria di autenticazione Fleet Engine, i JWT devono essere creati direttamente nel tuo codebase. Per questo è necessario disporre di un comprensione dei JWT e del loro rapporto con Fleet Engine. Ecco perché 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 garantire 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 chiave privata da utilizzare (ottenuta dagli account di servizio) e la crittografia dell'algoritmo. La sezione delle rivendicazioni contiene informazioni quali l'ora di creazione del token, la durata del token, i servizi a cui il token che richiedono l'accesso e altre informazioni sull'autorizzazione per 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 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 00:00:00 UTC, 1° gennaio 1970. La richiesta non va a buon fine se il timestamp è più di un'ora nel futuro. |
authorization |
A seconda del caso d'uso, possono 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 creare e firmare il JWT, consulta Autorizzazione dell'account di servizio senza OAuth. Puoi quindi collegare un token minted 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
i clienti autorizzati possono
accedere ai propri dati. Ad esempio, quando il tuo backend
emette un token web JSON per il dispositivo mobile di un corriere, tale token dovrebbe
contengono la dichiarazione deliveryvehicleid
con il valore della consegna del corriere
l'ID veicolo. Quindi, a seconda del ruolo di conducente, i token consentono l'accesso solo
l'ID specifico del veicolo di consegna e non 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 numeroBatchCreateTasksAPI
. Questa rivendicazione deve essere in formato array e deve contenere tutti gli ID attività necessari completare la richiesta. Non includeredelivervehicleid
,trackingid
otaskid
rivendicazioni.trackingid
: da utilizzare per chiamare ilGetTaskTrackingInfoAPI
. La rivendicazione deve corrisponda all'ID monitoraggio nella richiesta. Non includeredelivervehicleid
,taskid
otaskids
rivendicazioni.
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 deliveryvehicleid
, taskid
e trackingid
rivendicazioni. L'asterisco
("*") può essere utilizzato anche nella rivendicazione taskids
, ma deve essere l'unico elemento
nell'array.
Se vuoi creare e firmare un file JSON direttamente come porta token, anziché utilizzando i token di accesso OAuth 2.0, leggi le istruzioni per Autorizzazione dell'account di servizio senza OAuth nella documentazione per sviluppatori di identità.
Il meccanismo per collegare il token a una chiamata gRPC dipende dal linguaggio e il framework utilizzati per la chiamata. Il meccanismo per specificare un token a 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 monitoraggio della spedizione o prestazioni del parco risorse e casi d'uso specifici.
L'esempio seguente mostra un token per un'operazione per attività del 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 di attività del 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 veicolo di consegna da il 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 la tua app del conducente:
{
"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 il traffico privato l'ID della chiave. Puoi trovare questo valore nel campoprivate_key_id
del tuo il file JSON dell'account di servizio. - Per i campi
iss
esub
, specifica l'indirizzo email del tuo account di servizio. Puoi trovare questo valore nel campoclient_email
del tuo account di servizio JSON. - 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 valore server potrebbe segnalare un errore. - Per il campo
exp
specifica il timestamp di scadenza del token, in secondi dalle ore 00:00:00 UTC del 1° gennaio 1970. Il valore consigliato èiat
+ 3600.
Quando firmi il token da trasmettere a un dispositivo mobile o a un utente finale, assicurati che: per utilizzare il file delle credenziali per il ruolo Conducente consegna o Consumer. Altrimenti, il dispositivo mobile o l'utente finale avranno la possibilità di modificare informazioni a cui non dovrebbero avere accesso.