JSON-Webtokens

Ein JSON Web Token (JWT) ist ein offener Webstandard, der zur Authentifizierung und Autorisierung des Informationsaustauschs zwischen einem Client und einem Server verwendet wird. Wenn sich ein App-Nutzer zum ersten Mal mit den entsprechenden Rollenanmeldedaten anmeldet, erstellt der Server ein codiertes, digital signiertes JWT und gibt es für die Verwendung mit nachfolgenden Anfragen zurück. Bei diesem Vorgang wird der Nutzer sowohl authentifiziert als auch autorisiert, basierend auf seiner Kontorolle auf Routen, Dienste und Ressourcen zuzugreifen.

Für API-Methodenaufrufe aus Umgebungen mit geringem Vertrauensniveau (Smartphones und Browser) ist in Fleet Engine die Verwendung von JSON-Webtokens (JWTs) erforderlich.

Ein JWT wird auf Ihrem Server erstellt, signiert, verschlüsselt und an den Client übergeben. Es wird für nachfolgende Serverinteraktionen verwendet, bis es abläuft oder nicht mehr gültig ist.

Wichtige Details

Im Gegensatz zu API-Schlüsseln sind JWTs kurzlebig und beschränken Vorgänge auf diejenigen, die von der Rolle ausgeführt werden dürfen. Weitere Informationen zu JWTs finden Sie auf Wikipedia unter JSON Web Tokens. Weitere Informationen zu Zugriffsrollen finden Sie in diesem Leitfaden unter Dienstkontenrollen.

JWT-Elemente

JWTs enthalten einen Header und einen Anspruchsbereich. Der Header-Abschnitt enthält Informationen wie den privaten Schlüssel, der von Dienstkonten abgerufen wurde, und den Verschlüsselungsalgorithmus. Der Anspruchsbereich enthält Informationen wie die Erstellungszeit des JWT, die Gültigkeitsdauer, die Dienste, auf die das JWT Zugriff beansprucht, und andere Autorisierungsinformationen zur Eingrenzung des Zugriffs, z. B. die ID des Lieferfahrzeugs.

Die folgende Tabelle enthält allgemeine beschreibende Details zu JWT-Feldern sowie spezifische Informationen dazu, wo Sie die Werte für diese Felder in Ihrem Fleet Engine-Cloud-Projekt finden.

JWT-Headerfelder

Feld

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 Ihrer JSON-Datei für das Dienstkonto. Verwenden Sie einen Schlüssel von einem Dienstkonto mit der richtigen Berechtigungsstufe.
Felder für JWT-Anforderungen

Feld

Beschreibung

iss

Die E-Mail-Adresse Ihres Dienstkontos, die Sie im Feld client_email Ihrer JSON-Datei für das Dienstkonto finden.

Substitute

Die E-Mail-Adresse Ihres Dienstkontos, die Sie im Feld client_email Ihrer JSON-Datei für das Dienstkonto finden.

aud

Die SERVICE_NAME Ihres Dienstkontos, in diesem Fall https://fleetengine.googleapis.com/

iat

Der Zeitstempel, zu dem das JWT erstellt wurde, angegeben in Sekunden seit 00:00:00 UTC, January 1, 1970. Rechnen Sie rund 10 Minuten Verzögerung ein. Wenn der Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt, meldet der Server möglicherweise einen Fehler.

exp

Der Zeitstempel, wann das JWT abläuft, angegeben in Sekunden seit 00:00:00 UTC, January 1, 1970. Die Anfrage schlägt fehl, wenn der Zeitstempel mehr als eine Stunde in der Zukunft liegt.

Autorisierung

Je nach Anwendungsfall kann deliveryvehicleid, trackingid, taskid oder taskids enthalten sein.

Wenn Sie „taskids“ angeben, muss der Autorisierungsbereich ein Array in einem der folgenden Formate sein:

"taskids": ["task_id_one","task_id_two"]

oder

"taskids": ["*"]

Fleet Engine-JWT-Anforderungen

Fleet Engine verwendet private Ansprüche. Durch die Verwendung privater Ansprüche wird sichergestellt, dass nur autorisierte Clients auf ihre eigenen Daten zugreifen können.

Wenn Ihr Server beispielsweise ein JSON Web Token für das Mobilgerät eines Fahrers ausstellt, sollte es entweder die vehicleid-Anforderung oder die deliveryvehicleid-Anforderung mit dem Wert der Fahrzeug-ID dieses Fahrers enthalten. Je nach Fahrerrolle ermöglichen JWTs dann nur den Zugriff für die jeweilige Fahrzeug-ID und nicht für eine beliebige andere Fahrzeug-ID.

Fleet Engine verwendet die folgenden privaten Ansprüche:

On-Demand-Fahrten

  • vehicleid:
    • Das Driver SDK verwendet diesen Anspruch immer, unabhängig davon, ob es für eine Fahrt oder ein Fahrzeug verwendet wird. Das Fleet Engine-Backend sorgt dafür, dass das Fahrzeug dem angeforderten Trip zugeordnet ist, bevor die Änderung vorgenommen wird.
    • Das JWT kann sowohl Fahrzeug- als auch Fahrtenvorgänge abdecken, auch wenn dies nicht erforderlich ist. Das kann die Implementierung der JWT-Signierung vereinfachen.
  • tripid:
    • Das Consumer SDK verwendet diesen Anspruch immer.
    • Das JWT kann sowohl Fahrzeug- als auch Fahrtenvorgänge abdecken, auch wenn dies nicht erforderlich ist. Dies kann die Implementierung der Tokensignierung vereinfachen.

Geplante Aufgaben

  • deliveryvehicleid

    Wird beim Aufrufen von APIs pro Lieferfahrzeug verwendet.

  • taskid

    Wird beim Aufrufen von APIs für einzelne Aufgaben verwendet.

  • taskids

    Wird beim Aufrufen von BatchCreateTasksAPI verwendet. Dieser Anspruch muss in Arrayform vorliegen und das Array sollte alle Aufgaben-IDs enthalten, die zum Ausführen der Anfrage erforderlich sind. Fügen Sie keine Ansprüche für delivervehicleid, trackingid oder taskid hinzu.

  • trackingid

    Wird beim Aufrufen der GetTaskTrackingInfoAPI verwendet. Die Anspruchs-ID muss mit der Tracking-ID in der Anfrage übereinstimmen. Fügen Sie keine Ansprüche für delivervehicleid, taskid oder taskids hinzu.

Nächste Schritte