In diesem Dokument erfahren Sie, wie Sie JSON Web Tokens ausstellen, um Ihren Web- und mobilen Apps Zugriff auf Fleet Engine-Daten zu ermöglichen. Falls Sie dies noch nicht getan haben, lesen Sie JSON Web Tokens im Abschnitt Sicherheit in Fleet Engine. Mit dem Fleet Engine-Dienst können Sie JWTs auf eine der folgenden Arten ausgeben:
- Autorisierungsbibliothek verwenden: Google empfiehlt diesen Ansatz, wenn Ihre Codebasis in Java geschrieben ist. Diese Bibliothek kümmert sich um die Ausstellung von JWTs für alle Anwendungsfälle, die Sie für den Dienst benötigen, und vereinfacht die Implementierung erheblich.
- Eigene JWTs erstellen: Wenn Sie unsere JWT-Bibliothek nicht verwenden können, müssen Sie diese in Ihre eigene Codebasis integrieren. Dieser Abschnitt enthält die verschiedenen Beispiele für JWTs für jedes Szenario.
Funktionsweise von JWTs
In nicht vertrauenswürdigen Umgebungen wie Smartphones und Webbrowsern gibt dein Back-End-Server JWTs aus, die so funktionieren:
Der Clientcode, der in einer Umgebung mit wenig Vertrauen ausgeführt wird, ruft den Servercode auf, der in einer vollständig vertrauenswürdigen Umgebung ausgeführt wird, um das entsprechende JWT zur Übergabe an Fleet Engine anzufordern.
JWTs sind mit Dienstkonten verknüpft. Anfragen, die an die Fleet Engine gesendet werden, sind daher implizit mit dem Dienstkonto verknüpft, das das JWT signiert hat.
JWT-Ansprüche beschränken die Ressourcen, auf die der Client zugreifen darf, weiter, z. B. bestimmte Fahrzeuge, Fahrten oder Aufgaben.
Autorisierungsbibliothek für Java verwenden
Informationen zur Verwendung der Fleet Engine-Autorisierungsbibliothek für Java finden Sie im GitHub-Repository. Die Bibliothek vereinfacht das Erstellen von Fleet Engine-JWTs und signiert sie sicher. Sie enthält Folgendes:
- Projektabhängigkeitserklärungen
- Eine vollständige Liste aller Dienstkontorollen für Fahrten auf Abruf oder geplante Aufgaben
- Mechanismen zur Tokensignierung, die keine Anmeldedatendateien verwenden, z. B. die Identität eines Dienstkontos
- Hängt signierte Tokens an ausgehende Anfragen an, die entweder über einen gRPC-Stub oder eine GAPIC-Clientbibliothek (Google API Codegen) gesendet werden.
- Anleitung zum Integrieren der Unterzeichner in Fleet Engine-Clientbibliotheken
Wenn Sie JWTs über Ihren Code ausgeben
Wenn Sie die Autorisierungsbibliothek für Java nicht verwenden können, müssen Sie JWTs in Ihrer eigenen Codebasis implementieren. Dieser Abschnitt enthält einige Richtlinien zum Erstellen eigener Tokens. Eine Liste der JWT-Felder und -Anforderungen finden Sie unter JSON Web Tokens im Abschnitt Sicherheit in Fleet Engine. Informationen zu den von Fleet Engine verwendeten Dienstkontorollen finden Sie unter Dienstkontorollen. Im folgenden Abschnitt finden Sie eine Liste der JWT-Beispiele für On-Demand-Fahrten oder geplante Aufgaben.
Allgemeine Richtlinien
- Geeignete Dienstkonten und Rollen verwenden Das Dienstkonto und die zugehörige Rolle sorgen dafür, dass der Nutzer, der das Token anfordert, berechtigt ist, die Informationen aufzurufen, auf die ihm das Token Zugriff gewährt. Zum Beispiel:
- Wenn Sie ein JWT signieren, das an ein Mobilgerät übergeben werden soll, verwenden Sie das Dienstkonto für die Rolle „Driver“ oder „Consumer SDK“. Andernfalls kann das Mobilgerät Daten ändern und auf Daten zugreifen, auf die es keinen Zugriff haben sollte.
- Wenn Sie das JWT signieren, das für privilegierte Aufrufe verwendet werden soll, verwenden Sie bei Verwendung von ADCs oder JWTs das Dienstkonto mit der richtigen Rolle „Fleet Engine Admin“. Andernfalls schlägt der Vorgang fehl.
- Teilen Sie nur die erstellten Tokens. Geben Sie die Anmeldedaten, die zum Erstellen der Tokens verwendet wurden, niemals weiter.
- Bei gRPC-Aufrufen hängt der Mechanismus zum Anhängen des Tokens von der Sprache und dem Framework ab, die für den Aufruf verwendet werden. Zum Angeben eines Tokens für einen HTTP-Aufruf muss ein
Authorization
-Header mit einem Inhabertoken angegeben werden, dessen Wert das Token ist. - Geben Sie eine Ablaufzeit zurück. Ihr Server muss ein Ablaufdatum für das Token zurückgeben, normalerweise in Sekunden.
- Wenn Sie ein JSON-Objekt direkt als Tokeninhaber erstellen und signieren müssen, anstatt OAuth 2.0-Zugriffstokens zu verwenden, lesen Sie die Anleitung zur Autorisierung von Dienstkonten ohne OAuth in der Identity Developer-Dokumentation.
Für On-Demand-Reisen
- Fügen Sie beim Erstellen der JWT-Nutzlast im Abschnitt „Autorisierung“ einen zusätzlichen Anspruch hinzu, bei dem der Schlüssel
vehicleid
odertripid
auf den Wert der Fahrzeug- oder Fahrt-ID festgelegt ist, für die der Aufruf erfolgt.
Für geplante Aufgaben
- Wenn Ihr Server andere APIs aufruft, müssen auch die Tokens die entsprechende Anforderung enthalten. Dazu haben Sie folgende Möglichkeiten:
- Legen Sie für den Wert jedes Schlüssels
*
fest. - Gewähren Sie dem Nutzer Zugriff auf alle
taskids
unddeliveryvehicleids
. Dazu fügen Sie im Autorisierungsabschnitt eine zusätzliche Anforderung mit den Schlüsselntaskid
unddeliveryvehicleid
hinzu. - Wenn das Sternchen (
*
) in dertaskids
-Anforderung verwendet wird, muss es das einzige Element im Array sein.
- Legen Sie für den Wert jedes Schlüssels
JWT-Beispiele für On-Demand-Fahrten
Dieser Abschnitt enthält JWT-Beispiele für gängige Szenarien, wenn Sie On-Demand-Fahrten nutzen.
Beispiel für ein Token für eine Aktion in einer Fahrer-App
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"vehicleid": "driver_12345"
}
}
Beispieltoken für einen Nutzer-App-Vorgang
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"tripid": "trip_54321"
}
}
JWT-Beispiele für geplante Aufgaben
Dieser Abschnitt enthält ein JWT-Beispiel für typische Szenarien bei Verwendung geplanter Aufgaben.
Beispieltoken für eine 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"
}
}
Beispiel für ein Token für eine Verbraucher-App
{
"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"
}
}
JWT-Beispiele für Flottenvorgänge
In diesem Abschnitt finden Sie ein JWT-Beispiel für ein typisches Szenario bei Flottenoperationen.
Beispieltoken zum Verfolgen aller Aufgaben und Fahrzeuge in einer Flotte
Das folgende Beispiel ist ein Token, das alle Aufgaben und Fahrzeuge in der Flotte über eine webbasierte Anwendung verfolgt, die von einem Operator verwendet wird. Für diese Vorgänge sind mehr Berechtigungen erforderlich als für Clientanwendungen. Informationen zur clientseitigen Implementierung, bei der dieses Token verwendet wird, finden Sie unter JavaScript-Fleet Tracking Library einrichten:
Signieren Sie das Token mit der Cloud IAM-Rolle
Fleet Engine Delivery Fleet Reader
.
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
"sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"scope": "https://www.googleapis.com/auth/xapi",
"authorization": {
"taskid": "*",
"deliveryvehicleid": "*",
}
}
Alternative Authentifizierungsmethode für Back-End-Servervorgänge
Google empfiehlt, Back-End-Servervorgänge mit ADC zu authentifizieren. Wenn Sie ADC nicht verwenden können und JWTs verwenden müssen, sehen Sie sich diese Beispiele an.
Beispieltoken für einen On-Demand-Back-End-Servervorgang
{ "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": { "vehicleid": "*", "tripid": "*" } }
Beispieltoken für einen geplanten Backend-Servervorgang
{ "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": "*" } }
Beispiel für ein Token für einen geplanten Vorgang zum Batch-Erstellen von Aufgaben auf dem 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": ["*"] } }
Beispiel für ein Token für einen geplanten Vorgang für ein Übermittlungsmedium auf dem 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": { "deliveryvehicleid": "*" } }
Nächste Schritte
- Überprüfen Sie Ihre Einrichtung, damit Sie ein Testfahrzeug erstellen und prüfen können, ob Ihre Tokens wie vorgesehen funktionieren.
- Informationen zur Verwendung von ADC anstelle von JWTs für Back-End-Servervorgänge finden Sie in der Übersicht über die Sicherheit.