In diesem Abschnitt werden die Konzepte der Authentifizierung und Autorisierung mit in die Fleet Engine integrieren.
Sie können die Funktionen der Last Mile Fleet Solution über in der Google Cloud Console Fleet Engine SDKs ist die Verwendung von JSON-Web-Tokens (JWTs) erforderlich, die von einem entsprechenden Service Konto.
Übersicht
Kunden-Back-Ends zur Authentifizierung und Autorisierung bei Fleet Engine sollten Folgendes verwenden: Standard-Anwendungsstandard Anmeldedaten Mechanismen.
Fleet Engine erhält auch Aufrufe aus Umgebungen mit niedrigem Vertrauen. wie Smartphones und Browser. Nur geheime Schlüssel für Dienstkonten schützen geeignet für vertrauenswürdige Umgebungen, werden Back-Ends generiert, signierte JSON Web Tokens (JWT) mit zusätzlichen, Fleet Engine-spezifischen Anforderungen die dann an nicht vertrauenswürdige Umgebungen wie Smartphones gesendet werden können.
Designprinzipien für die Authentifizierung
Der Authentifizierungsvorgang von Fleet Engine basiert auf den folgenden Designprinzipien.
Mit IAM-Rollen wird Folgendes definiert: Reihe von Berechtigungen für Ressourcen, die für ein Hauptkonto zulässig sind. Beispiel: Der Parameter Admin-Rollen haben Zugriff auf alle Funktionen der Standardanwendung. Anmeldedaten, während die Rolle „Nicht vertrauenswürdiger Treiber*“ nur zum Aktualisieren und auf die Verwendung von JWTs zur Authentifizierung Autorisierung.
Bei nicht vertrauenswürdigen Umgebungen beschränken JWT-Anforderungen die Entitäten, die die Dabei kann es sich um bestimmte Aufgaben oder Lieferfahrzeuge handeln.
Ihr Code, der in einer Umgebung mit wenig Vertrauen ausgeführt wird, muss zuerst auf Ihrem Code, der in einer vertrauenswürdigen Umgebung ausgeführt wird, um ein JWT auszugeben.
Fleet Engine führt bei API-Aufrufen für eine Ressource:
Das aufrufende Hauptkonto hat die entsprechenden Berechtigungen (über die Rolle Zuweisung) für die Aktion für die Ressource.
Bei Nicht-Administratorrollen stellen die in der Anfrage übergebenen JWT-Anforderungen den für die Ressource benötigt werden.
Authentifizierungsvorgang
Im folgenden Sequenzdiagramm werden diese Details zum Authentifizierungsvorgang veranschaulicht.
Der Flottenadministrator erstellt Dienstkonten.
Der Flottenadministrator weist den Dienstkonten bestimmte IAM-Rollen zu.
Der Flottenadministrator konfiguriert sein Backend mit den Dienstkonten und Standardanmeldedaten für Anwendungen.
Die Client-App fordert vom Kunden-Back-End ein JWT an. Der Antragsteller könnte wie die Driver-App, die Consumer-App oder eine Monitoring-App.
Das Backend des Kunden signiert und gibt ein JWT für den jeweiligen Dienst aus. Konto. Die Client-App empfängt das JWT.
Die Client-App stellt mithilfe des JWT eine Verbindung zu Fleet Engine her, um Daten zu lesen oder zu ändern Daten abhängig von den IAM-Rollen, die ihnen während der Einrichtungsphase zugewiesen wurden.
Cloud-Projekt einrichten
Erstellen Sie zum Einrichten Ihres Cloud-Projekts zuerst Ihr Projekt und dann Dienstkonten erstellen.
So erstellen Sie Ihr Google Cloud-Projekt:
- Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
- Aktivieren Sie im Dashboard „APIs und Dienste“ die Local Rides and Deliveries API
Dienstkonten und IAM-Rollen
Ein Dienstkonto ist ein eine spezielle Art von Konto, das von einer Anwendung und nicht von einer Person verwendet wird. In der Regel wird ein Dienstkonto zum Erstellen von JWTs verwendet, die von der Rolle abhängen. Das Risiko von Missbrauch minimieren können Sie mehrere Dienstkonten erstellen, jedes mit der Mindestanzahl von Rollen erforderlich ().
Last Mile Fleet Solution verwendet die folgenden Rollen:
Rolle | Beschreibung |
---|---|
Nutzer von vertrauenswürdigen Treibern von Fleet Engine Delivery
roles/fleetengine.deliveryTrustedDriver |
Gewährt die Berechtigung zum Erstellen und Aktualisieren von Lieferfahrzeugen und -aufgaben einschließlich der Aktualisierung des Standorts und des Aufgabenstatus des Lieferfahrzeugs oder Ergebnis. Von einem Dienstkonto mit dieser Rolle geprägte Tokens werden üblicherweise über die Mobilgeräte Ihres Fahrers oder Ihre Back-End-Server. |
Nicht vertrauenswürdiger Fleet Engine Delivery-Treibernutzer
roles/fleetengine.deliveryUntrustedDriver |
Gewährt die Berechtigung zum Aktualisieren des Standorts des Lieferfahrzeugs. Tokens erstellt von einem Dienstkonto mit dieser Rolle in der Regel Mobilgeräte der Fahrer. |
Fleet Engine Delivery-Nutzernutzer
roles/fleetengine.deliveryConsumer |
Gewährt die Berechtigung zum Suchen nach Aufgaben mithilfe einer Tracking-ID, Aufgabeninformationen zu lesen, aber nicht zu aktualisieren. Tokens erstellt von einem Dienstkonto mit dieser Rolle werden in der Regel von einer Übermittlung im Webbrowser des Nutzers. |
Fleet Engine Delivery-Administrator
roles/fleetengine.deliveryAdmin |
Gewährt Lese- und Schreibberechtigungen für Bereitstellungsressourcen. Hauptkonten mit dieser Rolle brauchen keine JWTs und sollten stattdessen Standardanmeldedaten. Benutzerdefinierte JWT-Anforderungen werden ignoriert. Diese Rolle sollte auf vertrauenswürdige Umgebungen (Kunden-Back-End) beschränkt. |
roles/fleetengine.deliverySuperUser |
Gewährt Berechtigungen für alle APIs für Lieferfahrzeuge und -aufgaben. Tokens erstellt von einem Dienstkonto mit dieser Rolle werden in der Regel aus Ihrem Back-End verwendet. Server. |
Leser von Fleet Engine Delivery-Flotten
roles/fleetengine.deliveryFleetReader |
Gewährt die Berechtigung zum Lesen von Lieferfahrzeugen und -aufgaben und zum Suchen nach Aufgaben mithilfe einer Tracking-ID. Von einem Dienstkonto mit diesem Attribut geprägte Tokens werden in der Regel über den Webbrowser eines Anbieters von Lieferflotten verwendet. |
Organisationen, die ihren Lieferfahrern Geräte zur Verfügung stellen, die von die Unternehmens-IT die Flexibilität nutzen kann, die die Fleet Engine bietet. Nutzerrolle „Trusted Driver User“ (Trusted Driver User) und wählen Sie aus, ob einige oder die gesamte Fleet Engine integriert werden soll. in der mobilen App interagieren.
Organisationen, die Richtlinien zum Verwenden eigener Geräte (Bring Your Own Device, BYOD) unterstützen, sollten sich für die Sicherheit der Fleet Engine-Rolle „Nicht vertrauenswürdiger Treibernutzer“ und nutzen nur die mobile App zum Senden von Aktualisierungen des Fahrzeugstandorts an Fleet Engine. Alle anderen Interaktionen sollten von den Backend-Servern des Kunden stammen.
Die Treiber und das Consumer SDK basieren auf diesen Standardrollen. Es ist jedoch möglich, benutzerdefinierte Rollen zu erstellen. mit denen sich ein beliebiger Satz von Berechtigungen kombinieren lässt. Das Treiber- und das Consumer-SDK zeigen Fehlermeldungen an, wenn ein erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, statt benutzerdefinierter Rollen werden die oben dargestellten Standardrollen verwendet.
Dienstkonto erstellen
Sie können ein Dienstkonto mit der IAM & Admin > Service Accounts
erstellen.
in der Google Cloud Console. Wählen Sie aus der Dropdown-Liste Rolle die Option
Fleet Engine und weisen Sie dem Dienstkonto eine der Rollen zu. Gut
um das Konto anzugeben, das mit der jeweiligen Rolle verknüpft ist.
Geben Sie dem Dienstkonto beispielsweise einen aussagekräftigen Namen.
Wenn Sie JWTs für nicht vertrauenswürdige Clients erstellen müssen, fügen Sie Nutzer mit der Rolle „Service Account Token Creator“ können Tokens erstellen. gcloud-Befehlszeilentools verwenden.
gcloud projects add-iam-policy-binding project-id \ --member=user:my-user@example.com \ --role=roles/iam.serviceAccountTokenCreator
Dabei ist my-user@example.com
die E-Mail-Adresse, die für Folgendes verwendet wird:
Authentifizieren Sie sich mit gcloud (gcloud auth list
--format='value(account)'
).
Fleet Engine-Auth-Bibliothek
Fleet Engine verwendet JWTs, um den Zugriff auf Fleet Engine APIs in nicht vertrauenswürdigen Quellen einzuschränken Umgebungen. Die Fleet Engine Auth Library, verfügbar auf GitHub vereinfacht Fleet Engine-JWTs erstellen und sicher signieren.
Die Bibliothek bietet folgende Vorteile:
- Vereinfacht das Erstellen von Fleet Engine-Tokens.
- Stellt Tokensignaturmechanismen bereit, die keine Anmeldedatendateien verwenden (z. B. Identitätsdiebstahl eines Dienstkontos)
JSON-Webtoken (JWT) für die Autorisierung erstellen
Wenn Sie die Fleet Engine Auth Library nicht verwenden, müssen JWTs die direkt in Ihrer Codebasis erstellt wurden. Dazu benötigen Sie sowohl eine von JWTs und deren Beziehung zu Fleet Engine. Aus diesem Grund Wir empfehlen UNBEDINGT, die Fleet Engine Auth Library zu nutzen.
In Fleet Engine bieten JWTs eine kurzlebige Authentifizierung und sicherzustellen, dass Geräte nur Fahrzeuge oder Aufgaben für die sie autorisiert sind. JWTs enthalten einen Header und einen Anforderungsabschnitt. Der Header-Abschnitt enthält Informationen wie die den von Dienstkonten abgerufenen privaten Schlüssel und die Verschlüsselung Algorithmus. Der Abschnitt zum Anspruch enthält Informationen wie die Erstellungszeit des Tokens, Gültigkeitsdauer des Tokens, das Behaupten des Zugriffs auf und andere Autorisierungsinformationen Zugriff z. B. die ID des Lieferfahrzeugs.Ein JWT-Header-Abschnitt enthält die folgenden Felder:
Feld | Beschreibung |
---|---|
alg |
Der zu verwendende Algorithmus. „RS256“. |
typ |
Der Tokentyp. „JWT“. |
kid |
Die private Schlüssel-ID Ihres Dienstkontos. Diesen Wert finden Sie im Feld „private_key_id“ der JSON-Datei Ihres Dienstkontos ein. Achten Sie darauf, einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe zu verwenden. |
Der Abschnitt für die JWT-Anforderungen enthält die folgenden Felder:
Feld | Beschreibung |
---|---|
iss |
Die E-Mail-Adresse Ihres Dienstkontos. |
sub |
Die E-Mail-Adresse Ihres Dienstkontos. |
aud |
Der SERVICE_NAME Ihres Dienstkontos, in diesem Fall https://fleetengine.googleapis.com/ |
iat |
Der Zeitstempel für die Erstellung des Tokens, angegeben in verstrichenen Sekunden seit 00:00:00 UTC am 1. Januar 1970. Planen Sie 10 Minuten für die Verzerrung ein. Wenn die Wenn der Zeitstempel zu weit in der Vergangenheit oder Zukunft liegt, meldet der Server möglicherweise einen Fehler. |
exp |
Der Zeitstempel für das Ablaufdatum des Tokens, angegeben in verstrichenen Sekunden seit 00:00:00 UTC am 1. Januar 1970. Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt. |
authorization |
Je nach Anwendungsfall kann „deliveryvehicleid“, „trackingid“, „taskid“ oder „taskids“. |
Beim Erstellen eines JWT-Tokens wird es signiert. Anleitungen und Codebeispiele zum Erstellen und Signieren des JWT, siehe Dienstkontoautorisierung ohne OAuth: Sie können dann ein miniertes Token an gRPC-Aufrufe oder andere verwendete Methoden anhängen. um auf Fleet Engine zuzugreifen.
JWT-Anforderungen
Last Mile Fleet Solution verwendet private Anforderungen. Durch die Verwendung privater Ansprüche wird sichergestellt,
und autorisierte Clients auf ihre eigenen Daten zugreifen können. Wenn Ihr Back-End
ein JSON Web Token für das Mobilgerät eines Zustellfahrers ausgibt, sollte dieses Token
die Anforderung deliveryvehicleid
mit dem Wert der Lieferung dieses Fahrers enthalten.
Fahrzeug-ID. Je nach Fahrerrolle ermöglichen Tokens dann den Zugriff nur für
die spezifische zu übermittelnde Fahrzeug-ID und keine andere beliebige Fahrzeug-ID.
Last Mile Fleet Solution verwendet die folgenden privaten Anforderungen:
deliveryvehicleid
: wird beim Aufrufen von APIs für Fahrzeuge pro Lieferung verwendet.taskid
: wird beim Aufrufen von APIs pro Aufgabe verwendet.taskids
: beim Aufrufen vonBatchCreateTasksAPI
verwenden. Dieser Anspruch muss in Arrayform angegeben, und das Array sollte alle Aufgaben-IDs enthalten, die für um die Anfrage abzuschließen. Geben Sie wederdelivervehicleid
,trackingid
nochtaskid
Ansprüche.trackingid
: wird beim Aufrufen vonGetTaskTrackingInfoAPI
verwendet. Der Anspruch muss mit der Tracking-ID in der Anfrage übereinstimmen. Geben Sie nichtdelivervehicleid
,taskid
- odertaskids
-Ansprüche
Das Token muss auch die entsprechende Anforderung enthalten, wenn Sie APIs aufrufen.
von Ihrem Back-End-Server, Sie können jedoch den Wert eines Sternchens verwenden,
("*") für deliveryvehicleid
-, taskid
- und trackingid
-Ansprüche. Das Sternchen
(„*“) kann auch im taskids
-Anspruch verwendet werden, muss aber das einzige Element sein
im Array.
Wenn Sie ein JSON-Format direkt als Token-Inhaber erstellen und signieren möchten, OAuth 2.0-Zugriffstoken verwenden, finden Sie in der Anleitung für Dienstkontoautorisierung ohne OAuth in der Dokumentation zu Identity Developer.
Der Mechanismus zum Anhängen des Tokens an einen gRPC-Aufruf hängt von der Sprache ab und Framework, das für den Anruf verwendet wird. Der Mechanismus zum Angeben eines Tokens HTTP-Aufruf ist die Einbindung eines Authorization-Headers mit einem Inhabertoken dessen Wert das Token ist, wie in den Autorisierungshinweisen für die jeweilige Person vermerkt. Versandverfolgung oder Flottenleistung Anwendungsfälle.
Das folgende Beispiel zeigt ein Token für einen Vorgang pro Aufgabe aus Ihrem Backend-Server:
{
"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": "*"
}
}
Das folgende Beispiel zeigt ein Token für einen Batch-Erstellungsvorgang für Aufgaben aus Ihrem Backend-Server:
{
"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": ["*"]
}
}
Das folgende Beispiel zeigt ein Token für einen Vorgang pro Lieferfahrzeug von deinem Back-End-Server:
{
"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": "*"
}
}
Das folgende Beispiel zeigt ein Token für Endnutzerkunden:
{
"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"
}
}
Das folgende Beispiel zeigt ein Token für Ihre Treiber-App:
{
"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"
}
}
- Geben Sie im Feld
kid
im Header den privaten Wert Ihres Dienstkontos an Schlüssel-ID. Sie finden diesen Wert im Feldprivate_key_id
Ihrer JSON-Datei des Dienstkontos. - Geben Sie in den Feldern
iss
undsub
die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert in Ihrem Dienstkonto im Feldclient_email
. JSON-Datei. - Geben Sie für das Feld
aud
https://SERVICE_NAME/ an. - Geben Sie im Feld
iat
den Zeitstempel der Erstellung des Tokens an. in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC) wiedergegeben. 10 Minuten warten für Verzerrungen. Wenn der Zeitstempel zu weit in der Vergangenheit oder Zukunft liegt, einen Fehler meldet. - Geben Sie im Feld
exp
den Zeitstempel für den Ablauf des Tokens an. in Sekunden seit dem 1. Januar 1970, 00:00:00 Uhr (UTC). Der empfohlene Wert istiat
+ 3.600.
Achten Sie beim Signieren des Tokens, das an ein Mobilgerät oder den Endnutzer übergeben werden soll, darauf, um die Anmeldedatendatei für die Rolle „Delivery Driver“ oder „Consumer“ zu verwenden. Andernfalls kann das Mobilgerät oder der Endnutzer Informationen, auf die sie keinen Zugriff haben sollten.