Wystaw tokeny sieciowe JSON

Z tego dokumentu dowiesz się, jak wystawiać tokeny internetowe JSON, aby umożliwić dostęp do danych Fleet Engine aplikacjom internetowym i mobilnym. Jeśli jeszcze nie masz tego za sobą, przeczytaj artykuł Tokeny sieciowe JSON w sekcji Zabezpieczenia we Fleet Engine. Za pomocą usługi Fleet Engine możesz wystawiać tokeny JWT na jeden z tych sposobów:

  • Używanie biblioteki autoryzacji – Google zaleca stosowanie tego podejścia, gdy kod źródłowy jest napisany w języku Java. Ta biblioteka obsługuje wystawianie tokenów JWT we wszystkich scenariuszach użycia, których możesz potrzebować w przypadku danej usługi, i znacznie upraszcza implementację.
  • Tworzenie własnych tokenów JWT – jeśli nie możesz użyć naszej biblioteki JWT, musisz ją umieścić w swojej bazie kodu. W tej sekcji znajdziesz różne przykłady tokenów JWT dla poszczególnych scenariuszy.

Jak działają tokeny JWT

W niezaufanych środowiskach, takich jak telefony komórkowe i przeglądarki internetowe, serwer backendu wysyła tokeny JWT, które działają w ten sposób:

  • Kod klienta działający w środowisku o niskim poziomie zaufania wywołuje kod serwera działający w środowisku o pełnym zaufaniu, aby poprosić o odpowiednie tokeny JWT do przekazania do Fleet Engine.

  • Tokeny JWT są powiązane z kontami usługi, więc żądania wysyłane do Fleet Engine są domyślnie powiązane z kontem usługi, które podpisano token JWT.

  • Twierdzenia JWT dodatkowo ograniczają zasoby, na których może działać klient, takie jak konkretne pojazdy, przejazdy lub zadania.

Korzystanie z biblioteki autoryzacji w języku Java

Aby użyć biblioteki autoryzacji Fleet Engine dla języka Java, otwórz repozytorium GitHub. Biblioteka upraszcza tworzenie tokenów JWT Fleet Engine i ich bezpieczne podpisywanie. Umożliwia:

  • Deklaracje zależności projektu
  • Pełną listę wszystkich ról konta usługi dotyczących podróży na żądanie lub zaplanowanych zadań
  • mechanizmy podpisywania tokenów inne niż korzystające z plików danych logowania, np. podszywanie się pod konto usługi.
  • Dołącza podpisane tokeny do żądań wychodzących wysyłanych z namiaru gRPC lub z biblioteki klienta Google API Codegen (GAPIC)
  • Instrukcje integracji osób podpisujących z bibliotekami klienta Fleet Engine

Jeśli wystawiasz tokeny JWT z kodu

Jeśli nie możesz użyć biblioteki autoryzacji dla Javy, musisz zaimplementować tokeny JWT w swojej własnej bazie kodu. Ta sekcja zawiera kilka wytycznych dotyczących tworzenia własnych tokenów. Listę pól i deklaracji JWT znajdziesz w sekcji Tokeny sieciowe JSON w sekcji Zabezpieczenia w Fleet Engine. Informacje o rolach konta usługi używanych przez Fleet Engine znajdziesz w artykule Role konta usługi. W następującej sekcji znajdziesz listę przykładów JWT dotyczących przejazdów na żądanie lub zaplanowanych zadań.

Ogólne wskazówki

  • Używanie odpowiednich kont usługi i ról Konto usługi i powiązana rola zapewniają, że użytkownik żądający tokenu ma uprawnienia do wyświetlania informacji, do których token zapewnia dostęp. W szczególności:
    • Jeśli podpisujesz token JWT, który ma zostać przekazany na urządzenie mobilne, użyj konta usługi dla roli Driver lub Consumer SDK. W przeciwnym razie urządzenie mobilne może modyfikować dane i uzyskiwać do nich dostęp.
    • Jeśli podpisujesz token JWT, aby używać go do wywołań z odpowiednimi uprawnieniami, używaj konta usługi z odpowiednią rolą administratora Fleet Engine, gdy korzystasz z ADC lub tokenów JWT. W przeciwnym razie operacja się nie powiedzie.
  • Udostępnij tylko utworzone tokeny. Nigdy nie udostępniaj danych logowania użytych do utworzenia tokenów.
  • W przypadku wywołań gRPC mechanizm dołączania tokena zależy od języka i platformy użytej do wywołania. Mechanizmem określania tokena w wywołaniu HTTP jest dołączenie nagłówka Authorization z tokenem uprawnień, którego wartość to token.
  • Zwracanie czasu wygaśnięcia. Serwer musi zwrócić czas ważności tokena, zwykle w sekundach.
  • Jeśli chcesz utworzyć i podpisać plik JSON bezpośrednio jako nośnik tokenów, a nie używać tokenów dostępu OAuth 2.0, zapoznaj się z instrukcjami dotyczącymi autoryzowania konta usługi bez OAuth w dokumentacji dla deweloperów tożsamości.

W przypadku podróży na żądanie

  • Podczas tworzenia ładunku JWT dodaj w sekcji autoryzacji dodatkową deklarację z kluczem vehicleid lub tripid ustawionym na wartość identyfikatora pojazdu lub identyfikatora podróży, którego dotyczy wywołanie.

Zaplanowane zadania

  • Gdy serwer wywołuje inne interfejsy API, tokeny muszą też zawierać odpowiednią deklarację. Aby to zrobić, wykonaj te czynności:
    • Ustaw wartość każdego klucza na *.
    • Przyznaj użytkownikowi dostęp do wszystkich elementów taskids i deliveryvehicleids. Aby to zrobić, dodaj w sekcji autoryzacji dodatkowy element żądania z kluczami taskid i deliveryvehicleid.
    • Gdy w deklaracji taskids używasz gwiazdki (*), musi to być jedyny element w tablicy.

Przykłady tokenów JWT w przypadku przejazdów na żądanie

W tej sekcji znajdziesz przykłady tokenów JWT na potrzeby typowych scenariuszy, jeśli korzystasz z przejazdów na żądanie.

Przykładowy token operacji w aplikacji sterownika

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

Przykładowy token operacji aplikacji dla konsumenta

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

Przykłady tokenów JWT dla zaplanowanych zadań

Ta sekcja zawiera przykład tokena JWT na potrzeby typowych scenariuszy, jeśli używasz zadań zaplanowanych.

Przykładowy token dla aplikacji dla kierowcy

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

Przykładowy token dla aplikacji dla konsumentów

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

Przykłady tokenów JWT do operacji dotyczących floty

W tej sekcji znajdziesz przykład tokena JWT używany w typowym scenariuszu operacji na flocie.

Przykładowy token do śledzenia wszystkich zadań i pojazdów we flocie

Poniższy przykład to token, który śledzi wszystkie zadania i pojazdy we flocie z użyciem aplikacji internetowej używanej przez operatora. Do tych operacji wymagane są większe uprawnienia niż w przypadku aplikacji klienckich. Informacje o implementacji po stronie klienta, która używa tego tokena, znajdziesz w artykule o konfigurowaniu biblioteki śledzenia flot w języku JavaScript:

  • Podpisz token przy użyciu roli Fleet Engine Delivery Fleet Reader w Cloud IAM.

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

Alternatywna metoda uwierzytelniania w przypadku operacji serwera w tle

Google zaleca używanie ADC do uwierzytelniania operacji serwera zaplecza. Jeśli nie możesz używać ADC i musisz używać tokenów JWT, zapoznaj się z tymi przykładami.

Przykładowy token operacji serwera backendu na żądanie

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

Przykładowy token dla zaplanowanej operacji serwera zaplecza

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

Przykładowy token dla zaplanowanej operacji tworzenia zadań w partiach na serwerze backendu

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

Przykładowy token operacji zaplanowanego serwera backendu dla konkretnego dostawy pojazdu

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

Co dalej?