Authentifizierung und Autorisierung

In diesem Abschnitt werden die Konzepte der Authentifizierung und Autorisierung in Bezug auf die Fleet Engine-Implementierung erläutert. Darin werden die Verfahren beschrieben, die Sie zum Sichern Ihrer Fleet Engine-Funktionsaufrufe ausführen müssen.

Sie können die von Last Mile Fleet Solution bereitgestellten Funktionen über die Google Cloud Console konfigurieren. Für diese APIs und SDKs sind JSON Web Tokens (JWTs) erforderlich, die mit Dienstkonten signiert wurden, die in der Cloud Console erstellt wurden.

Überblick

Im Rahmen des Autorisierungsmechanismus bietet Fleet Engine zusätzliche Sicherheit bei Aufrufen, die aus Umgebungen mit niedriger Vertrauenswürdigkeit stammen. Zu den vertrauenswürdigen Umgebungen gehören Smartphones und Browser. Darüber hinaus verwendet Fleet Engine das Prinzip der geringsten Berechtigung. Dabei sollten einem Aufruf nur die Berechtigungen erteilt werden, die für die Ausführung der Aufgabe erforderlich sind.

Zum Schutz von Funktionsaufrufen aus Umgebungen mit niedriger Vertrauenswürdigkeit hat Google einen Mechanismus entwickelt, bei dem Ihr Code ein Token auf Ihrem Back-End-Server erstellt, in einer vollständig vertrauenswürdigen Umgebung. Jeder Aufruf enthält eine vollständige Sicherheitsbeschreibung, die dann in ein JWT verschlüsselt wird, das Sie mit dem Aufruf aus einer beliebigen Umgebung übergeben.

Prinzipien des Authentifizierungsdesigns

Der Authentifizierungsablauf von Fleet Engine beinhaltet die folgenden Designprinzipien.

• IAM-Rollen definieren den Bereich der zulässigen Aktivitäten für den Aufrufer. Die Rolle SuperUser ist beispielsweise berechtigt, alles zu tun, während die Rolle Nicht vertrauenswürdiger Treiber nur minimale Standortaktualisierungen vornehmen darf.

• IAM-Rollen sind mit Dienstkonten verknüpft.

• JWT-Anforderungen schränken die Entitäten weiter ein, mit denen der Aufrufer arbeiten kann. Das können bestimmte Aufgaben oder Lieferfahrzeuge sein.

• An Fleet Engine gesendete Anfragen enthalten immer ein JWT.

  • Da JWTs mit Dienstkonten verknüpft sind, werden an Fleet Engine gesendete Anfragen implizit mit dem Dienstkonto verknüpft, das dem JWT zugeordnet ist.

• Um das entsprechende JWT anzufordern, das Sie dann an Fleet Engine übergeben können, muss Ihr Code, der in einer Low-Trust-Umgebung ausgeführt wird, zuerst den Code aufrufen, der in einer vollständig vertrauenswürdigen Umgebung ausgeführt wird.

• Fleet Engine führt die folgenden Sicherheitsprüfungen durch:

  1. IAM-Rollen, die mit dem Dienstkonto verknüpft sind, sorgen für die korrekte Autorisierung für den Aufrufer zum Ausführen des API-Aufrufs.

  2. Die in der Anfrage übergebenen JWT-Anforderungen stellen für den Aufrufer die korrekte Autorisierung bereit, mit der Entität zu arbeiten.

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 Backend mit den Dienstkonten.

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

5. Fleet Engine gibt ein JWT für das jeweilige Dienstkonto aus. Die Client-App empfängt das JWT.

6. Die Client-App verwendet das JWT, um sich mit Fleet Engine zu verbinden und Daten zu lesen oder zu ändern, je nachdem, welche IAM-Rollen ihnen während der Einrichtung 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-Superuser 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 einzuschränken. Die neue Authentifizierungsbibliothek von Fleet Engine, die auf GitHub verfügbar ist, 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).
• Hängt signierte Tokens an ausgehende Anfragen an, die von einem gRPC-Stub oder GAPIC-Client gesendet wurden.

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 SearchTasksAPI 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.