Authentifizierung und Autorisierung

In diesem Abschnitt werden die Konzepte der Authentifizierung und Autorisierung in Bezug auf die Einbindung in Fleet Engine erläutert.

Sie können die von Last Mile Fleet Solution bereitgestellten Funktionen über die Google Cloud Console konfigurieren. Fleet Engine SDKs erfordern die Verwendung von JSON Web Tokens (JWTs), die von einem entsprechenden Dienstkonto signiert wurden.

Überblick

Kunden-Back-Ends, die sich bei Fleet Engine authentifizieren und autorisieren, sollten Standardmechanismen für Standardanmeldedaten für Anwendungen verwenden.

Fleet Engine empfängt auch Aufrufe, die aus Umgebungen mit niedriger Vertrauenswürdigkeit wie Smartphones und Browsern stammen. Um geheime Schlüssel für Dienstkonten zu schützen, die nur für vertrauenswürdige Umgebungen geeignet sind, wird erwartet, dass die Back-Ends des Kunden signierte JSON Web Tokens (JWT) mit zusätzlichen Anforderungen speziell für Fleet Engine generieren, die dann an nicht vertrauenswürdige Umgebungen wie Smartphones ausgegeben werden können.

Prinzipien des Authentifizierungsdesigns

Der Authentifizierungsablauf von Fleet Engine beinhaltet die folgenden Designprinzipien.

• IAM-Rollen definieren eine Reihe von Berechtigungen für Ressourcen, die für ein Hauptkonto zulässig sind. Die Admin-Rolle darf beispielsweise alles mit Standardanmeldedaten für Anwendungen tun, während die Rolle „Nicht vertrauenswürdiger Fahrer*“ nur den Fahrzeugstandort aktualisieren und auf JWTs zur Authentifizierung und Autorisierung beschränkt ist.

• In nicht vertrauenswürdigen Umgebungen schränken JWT-Anforderungen die Entitäten weiter ein, mit denen der Aufrufer Vorgänge ausführen kann. Das können bestimmte Aufgaben oder Lieferfahrzeuge sein.

• Dein Code, der in einer Low-Trust-Umgebung ausgeführt wird, muss zuerst deinen Code aufrufen, der in einer vertrauenswürdigen Umgebung ausgeführt wird, um ein JWT auszugeben.

• Fleet Engine führt bei API-Aufrufen für eine Ressource die folgenden Sicherheitsprüfungen durch:

  1. Das aufrufende Hauptkonto hat die entsprechenden Berechtigungen (über Rollenzuweisung) für die Aktion für die Ressource.

  2. Bei Rollen ohne Administratorberechtigungen bieten die in der Anfrage übergebenen JWT-Anforderungen die erforderliche Berechtigung für die Ressource.

Authentifizierungsvorgang

Das folgende Sequenzdiagramm zeigt diese Details des Authentifizierungsablaufs.

1. Der Flottenadministrator erstellt Dienstkonten.

2. Der Flottenadministrator weist den Dienstkonten bestimmte IAM-Rollen zu.

3. Der Flottenadministrator konfiguriert sein Back-End mit den Dienstkonten und den Standardanmeldedaten für Anwendungen.

4. Die Client-App fordert ein JWT vom Kunden-Back-End an. Der Anforderer kann die Driver-App, die Consumer-App oder eine Monitoring-App sein.

5. Das Back-End des Kunden signiert und gibt ein JWT für das jeweilige Dienstkonto aus. Die Client-App empfängt das JWT.

6. Die Client-App verwendet das JWT, um eine Verbindung zu Fleet Engine herzustellen, um Daten zu lesen oder zu ändern, je nachdem, welche IAM-Rollen ihnen in der Einrichtungsphase zugewiesen wurden.

Cloud-Projekt einrichten

Erstellen Sie zum Einrichten Ihres Cloud-Projekts zuerst das Projekt und dann Dienstkonten.

So erstellen Sie Ihr Google Cloud-Projekt:

1. Erstellen Sie mit der Google Cloud Console ein Google Cloud-Projekt.
2. Aktiviere im Dashboard „APIs und Dienste“ die Local Rides and Deliveries API.

Dienstkonten und IAM-Rollen

Ein Dienstkonto ist 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 je nach Rolle unterschiedliche Berechtigungssätze gewähren. Um Missbrauch zu vermeiden, können Sie mehrere Dienstkonten mit jeweils dem erforderlichen Mindestsatz an Rollen erstellen ().

Die Last Mile Fleet Solution verwendet die folgenden Rollen:

Rolle	Beschreibung
Vertrauenswürdiger Driver-Nutzer 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 des Lieferfahrzeugs sowie des Aufgabenstatus oder -ergebnisses. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel auf den Mobilgeräten des Auslieferungstreibers oder von Ihren Back-End-Servern verwendet.
Nicht vertrauenswürdiger Fleet Engine Delivery-Fahrernutzer roles/fleetengine.deliveryUntrustedDriver	Gewährt die Berechtigung zum Aktualisieren des Standorts des Lieferfahrzeugs. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel auf den Mobilgeräten des Fahrers verwendet.
Fleet Engine Delivery-Nutzernutzer roles/fleetengine.deliveryConsumer	Gewährt die Berechtigung zum Suchen nach Aufgaben mit einer Tracking-ID und zum Lesen, aber nicht Aktualisieren von Aufgabeninformationen. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel im Webbrowser eines Nutzers für die Bereitstellung verwendet.
Fleet Engine Delivery-Administrator<> roles/fleetengine.deliveryAdmin	Gewährt Lese- und Schreibberechtigungen für Bereitstellungsressourcen. Hauptkonten mit dieser Rolle müssen keine JWTs verwenden und sollten stattdessen Standardanmeldedaten für Anwendungen verwenden. Benutzerdefinierte JWT-Anforderungen werden ignoriert. Diese Rolle sollte auf vertrauenswürdige Umgebungen (Kunden-Backend) beschränkt sein.
Fleet Engine Delivery-Superuser **(EINGESTELLT)** roles/fleetengine.deliverySuperUser	Gewährt die Berechtigung für alle APIs für Lieferfahrzeuge und -aufgaben. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel von Ihren Back-End-Servern verwendet.
Leser von Fleet Engine Delivery-Flotten roles/fleetengine.deliveryFleetReader	Gewährt die Berechtigung zum Lesen von Lieferfahrzeugen und -aufgaben sowie zum Suchen nach Aufgaben mithilfe einer Tracking-ID. Tokens, die von einem Dienstkonto mit dieser Rolle erstellt werden, werden in der Regel im Webbrowser eines Betreibers der Bereitstellungsflotten verwendet.

Organisationen, die ihren Bereitstellungsfahrern Geräte zur Verfügung stellen, die von der IT-Abteilung verwaltet werden, können die Flexibilität der Fleet Engine-Rolle „Trusted Driver User“ nutzen und einige oder alle Fleet Engine-Interaktionen in die mobile App einbinden.

Organisationen, die Richtlinien zum Verwenden eigener Geräte (Bring Your Own Device, Nutzung eigener Geräte) unterstützen, sollten sich für die Sicherheit der Rolle „Nicht vertrauenswürdiger Fahrernutzer in Fleet Engine“ entscheiden und sich nur auf die mobile App verlassen, um Aktualisierungen des Fahrzeugstandorts an Fleet Engine zu senden. Alle anderen Interaktionen sollten von den Back-End-Servern des Kunden stammen.

Die Treiber- und Consumer SDKs basieren auf diesen Standardrollen. Es ist jedoch möglich, benutzerdefinierte Rollen zu erstellen, mit denen beliebige Berechtigungen gebündelt werden können. Im Treiber- und im Consumer SDK werden Fehlermeldungen angezeigt, wenn eine erforderliche Berechtigung fehlt. Daher empfehlen wir dringend, die oben beschriebenen Standardrollen anstelle von benutzerdefinierten Rollen zu verwenden.

Dienstkonto erstellen

Sie können ein Dienstkonto in der Google Cloud Console auf dem Tab IAM & Admin > Service Accounts erstellen. Wählen Sie in der Drop-down-Liste „Rolle“ die Option „Fleet Engine“ aus und weisen Sie dem Dienstkonto eine der Rollen zu. Es empfiehlt sich, das Konto anzugeben, das mit jeder 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, können Sie Nutzer zur Rolle „Ersteller von Dienstkonto-Tokens“ hinzufügen, um Tokens mit gcloud-Befehlszeilentools zu erstellen.

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Dabei ist [e-mail] die E-Mail-Adresse, die zur Authentifizierung bei gcloud verwendet wird (gcloud auth list --format='value(account)').

Hinweis: Dadurch erhält der Empfänger die Berechtigung, die Identität eines beliebigen Dienstkontos im Projekt zu übernehmen. Wenn Sie detailliertere Berechtigungen festlegen möchten, folgen Sie der IAM-Dokumentation zum Festlegen von Rollenbindungen an ein bestimmtes Dienstkonto.

Fleet Engine-Authentifizierungsbibliothek

Fleet Engine verwendet JWTs, um den Zugriff auf Fleet Engine APIs in nicht vertrauenswürdigen Umgebungen einzuschränken. Die auf GitHub verfügbar Fleet Engine-Authentifizierungsbibliothek vereinfacht die Erstellung von Fleet Engine-JWTs und signiert sie sicher.

Die Bibliothek bietet folgende Vorteile:

• Vereinfacht das Erstellen von Fleet Engine Tokens.
• Bietet andere Tokensignaturmechanismen als die Verwendung von Dateien mit Anmeldedaten (z. B. die Identität eines Dienstkontos).

Wichtig: Wir empfehlen dringend, die Fleet Engine-Authentifizierungsbibliothek für alle Java-Implementierungen zu verwenden.

JSON-Webtoken (JWT) für die Autorisierung erstellen

Wenn Sie die Fleet Engine-Authentifizierungsbibliothek nicht verwenden, müssen JWTs direkt in Ihrer Codebasis erstellt werden. Dazu benötigen Sie ein tiefgreifendes Verständnis von JWTs und deren Beziehung zu Fleet Engine. Aus diesem Grund empfehlen wir dringend, die Nutzung der Fleet Engine-Authentifizierungsbibliothek zu nutzen.

In Fleet Engine bieten JWTs eine kurzlebige Authentifizierung und sorgen dafür, dass Geräte nur Fahrzeuge oder Aufgaben ändern können, für die sie autorisiert sind. JWTs enthalten einen Header und einen Anforderungsabschnitt. Der Header-Abschnitt enthält Informationen wie den zu verwendenden privaten Schlüssel (von Dienstkonten erhalten) und den Verschlüsselungsalgorithmus. Der Claim-Abschnitt enthält Informationen wie die Erstellungszeit des Tokens, die Lebensdauer des Tokens, die Dienste, auf die das Token Zugriff beansprucht, und andere Autorisierungsinformationen für den Zugriffsbereich, z. B. die Lieferfahrzeug-ID.

Ein JWT-Header enthält die folgenden Felder:

Field	Beschreibung
alg	Der zu verwendende Algorithmus. „RS256“.
typ	Der Typ des Tokens. „JWT“.
Kind	Die ID des privaten Schlüssels Ihres Dienstkontos. Sie finden diesen Wert im Feld „private_key_id“ der JSON-Datei Ihres Dienstkontos. Achten Sie darauf, einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe zu verwenden.

Ein Bereich für JWT-Anforderungen enthält die folgenden Felder:

Field	Beschreibung
iss	Die E-Mail-Adresse Ihres Dienstkontos.
sub	Die E-Mail-Adresse Ihres Dienstkontos.
aud	SERVICE_NAME Ihres Dienstkontos, in diesem Fall https://fleetengine.googleapis.com/
iat	Der Zeitstempel für die Erstellung des Tokens, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC). Warten Sie 10 Minuten für eine Verzerrung. Wenn der Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt, meldet der Server möglicherweise einen Fehler.
exp	Der Zeitstempel für den Ablauf des Tokens, angegeben in Sekunden seit dem 1. Januar 1970 um 00:00:00 Uhr (UTC). Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt.
authorization	Je nach Anwendungsfall kann dieses Attribut „deliveryvehicleid“, „trackingid“, „taskid“ oder „taskids“ enthalten.

Das Erstellen eines JWT-Tokens bezieht sich auf das Signieren. Eine Anleitung und Codebeispiele zum Erstellen und Signieren des JWT finden Sie unter Dienstkontoautorisierung ohne OAuth. Anschließend können Sie ein erstelltes Token an gRPC-Aufrufe oder andere Methoden für den Zugriff auf Fleet Engine anhängen.

JWT-Anforderungen

Die Last Mile Fleet Solution verwendet private Ansprüche. Die Verwendung privater Anforderungen stellt sicher, dass nur autorisierte Clients auf ihre eigenen Daten zugreifen können. Wenn Ihr Back-End beispielsweise ein JSON-Webtoken für das Mobilgerät eines Zustellers ausgibt, sollte dieses Token die Anforderung deliveryvehicleid mit dem Wert der Lieferfahrzeug-ID dieses Fahrers enthalten. Je nach Fahrerrolle ermöglichen Tokens dann nur den Zugriff für die jeweilige Übermittlungs-Fahrzeug-ID und nicht für eine andere beliebige Fahrzeug-ID.

Die Last Mile Fleet Solution verwendet die folgenden privaten Anforderungen:

• deliveryvehicleid: wird beim Aufrufen von APIs für einzelne Lieferungen verwendet.
• taskid: wird beim Aufrufen von APIs pro Aufgabe verwendet.
• taskids – beim Aufrufen von BatchCreateTasksAPI verwenden. Diese Anforderung muss in Arrayform vorliegen und das Array sollte alle Aufgaben-IDs enthalten, die zum Abschließen der Anfrage erforderlich sind. Die Ansprüche delivervehicleid, trackingid oder taskid dürfen nicht verwendet werden.
• trackingid: wird beim Aufrufen von GetTaskTrackingInfoAPI verwendet. Die Behauptung muss mit der Tracking-ID in der Anfrage übereinstimmen. Die Anforderungen delivervehicleid, taskid oder taskids dürfen nicht verwendet werden.

Das Token muss auch die entsprechende Anforderung enthalten, wenn Sie APIs von Ihrem Back-End-Server aufrufen. Sie können jedoch den speziellen Wert eines Sternchens ("*") für die Anforderungen deliveryvehicleid, taskid und trackingid verwenden. Das Sternchen ("*") kann auch in der taskids-Anforderung verwendet werden, muss aber das einzige Element im Array sein.

Wenn Sie eine JSON-Datei direkt als Tokeninhaber erstellen und signieren möchten, statt OAuth 2.0-Zugriffstokens zu verwenden, lesen Sie die Anleitung zur Dienstkontoautorisierung ohne OAuth in der Dokumentation für Identity Developer.

Der Mechanismus zum Anhängen des Tokens an einen gRPC-Aufruf hängt von der Sprache und dem Framework ab, die für den Aufruf verwendet wurden. Der Mechanismus zum Angeben eines Tokens für einen HTTP-Aufruf besteht darin, einen Autorisierungsheader mit einem Inhabertoken einzufügen, dessen Wert das Token ist. Dies wird in den Autorisierungshinweisen für die individuellen Anwendungsfälle Sendungsverfolgung oder Flottenleistung beschrieben.

Das folgende Beispiel zeigt ein Token für einen Vorgang pro Aufgabe von Ihrem Back-End-Server:

    {
      "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": "*"
       }
    }

Das folgende Beispiel zeigt ein Token für einen Vorgang zur Batcherstellung von Ihrem Back-End-Server:

    {
      "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": ["*"]
       }
    }

Das folgende Beispiel zeigt ein Token für einen Vorgang pro Auslieferungsfahrzeug von Ihrem Back-End-Server:

    {
      "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": "*"
       }
    }

Das folgende Beispiel zeigt ein Token für Endnutzer:

    {
      "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"
       }
    }

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": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

• Geben Sie im Header für das Feld kid die ID des privaten Schlüssels Ihres Dienstkontos an. Sie finden diesen Wert im Feld private_key_id der JSON-Datei Ihres Dienstkontos.
• Geben Sie in den Feldern iss und sub die E-Mail-Adresse Ihres Dienstkontos an. Sie finden diesen Wert im Feld client_email der JSON-Datei Ihres Dienstkontos.
• Geben Sie für das Feld aud https://SERVICE_NAME/ an.
• Geben Sie im Feld iat den Zeitstempel der Erstellung des Tokens in Sekunden an, die seit dem 1. Januar 1970, 00:00:00 Uhr (UTC) vergangen sind. Warten Sie 10 Minuten für Verzerrungen. Wenn der Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt, meldet der Server möglicherweise einen Fehler.
• Geben Sie im Feld exp den Zeitstempel für den Ablauf des Tokens in Sekunden ab 00:00:00 Uhr (UTC) am 1. Januar 1970 an. Der empfohlene Wert ist iat + 3.600.

Verwende beim Signieren des Tokens, das an ein Mobilgerät oder einen Endnutzer weitergeleitet werden soll, die Anmeldedatendatei für die Rolle „Delivery Driver“ oder „Consumer“. Andernfalls kann das Mobilgerät oder der Endnutzer Informationen ändern oder anzeigen, auf die sie keinen Zugriff haben sollten.