Wystaw tokeny sieciowe JSON

Z tego dokumentu dowiesz się, jak wydawać tokeny sieciowe JSON w ramach umożliwiania aplikacjom internetowym i mobilnym dostępu do danych Fleet Engine. Jeśli jeszcze tego nie zrobisz, przeczytaj sekcję Tokeny sieciowe JSON w sekcji Bezpieczeństwo w Fleet Engine. W usłudze Fleet Engine możesz wydawać tokeny JWT na jeden z tych sposobów:

• Użyj biblioteki autoryzacji – Google zaleca to podejście jeśli Twoja baza kodu jest napisana w języku Java. Ta biblioteka obsługuje wydawanie tokenów JWT we wszystkich scenariuszach użycia, które mogą być potrzebne w usłudze, i znacznie upraszcza implementację.
• Utwórz własne tokeny JWT—Jeśli nie możesz użyć naszej biblioteki JWT, musisz wbudować je w swoją bazę kodu. W tej sekcji znajdziesz różne przykłady tokenów JWT dla każdego scenariusza.

Jak działają tokeny JWT

W przypadku środowisk niezaufanych, takich jak telefony komórkowe i przeglądarki internetowe, serwer backendu wydaje 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 poziomie zaufania, aby poprosić o odpowiedni token JWT, który ma zostać przekazany do Fleet Engine.

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

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

Korzystanie z biblioteki autoryzacji dla języka Java

Aby używać biblioteki autoryzacji Fleet Engine dla języka Java, otwórz repozytorium GitHub. Biblioteka upraszcza tworzenie tokenów JWT Fleet Engine i bezpiecznie je podpisuje. Zapewnia ona te funkcje:

• Deklaracje zależności projektu
• Pełna lista wszystkich ról konta usługi w przypadku przejazdów na żądanie lub zaplanowanych zadań
• Mechanizmy podpisywania tokenów inne niż używanie plików danych logowania, np. podszywanie się pod konto usługi
• Dołącza podpisane tokeny do żądań wychodzących wysyłanych ze stubu gRPC lub biblioteki klienta Google API Codegen (GAPIC)
• Instrukcje dotyczące integrowania sygnatariuszy z bibliotekami klienta Fleet Engine

Wydawanie tokenów JWT z kodu

Jeśli nie możesz użyć biblioteki autoryzacji dla języka Java, musisz zaimplementować tokeny JWT w swojej bazie kodu. W tej sekcji znajdziesz kilka wskazówek dotyczących tworzenia własnych tokenów. Listę pól i deklaracji JWT znajdziesz w sekcji Tokeny sieciowe JSON w sekcji Bezpieczeństwo w Fleet Engine. Role konta usługi używane przez Fleet Engine znajdziesz w sekcji Role konta usługi. Listę przykładów tokenów JWT w przypadku przejazdów na żądanie lub zaplanowanych zadań znajdziesz w następnej sekcji.

Ogólne wskazówki

• Używaj odpowiednich kont usługi i ról. Konto usługi i powiązana z nim rola zapewniają, że użytkownik żądający tokena jest uprawniony do wyświetlania informacji, do których token przyznaje mu 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 z rolą pakietu SDK kierowcy lub konsumenta. W przeciwnym razie urządzenie mobilne może zmieniać dane i uzyskiwać do nich dostęp.
  • Jeśli podpisujesz token JWT, który ma być używany do wywołań z uprawnieniami, użyj konta usługi z odpowiednią rolą administratora Fleet Engine, gdy używasz ADC lub tokenów JWT. W przeciwnym razie operacja się nie powiedzie.
• Udostępniaj tylko utworzone tokeny. Nigdy nie udostępniaj danych logowania używanych do tworzenia tokenów.
• W przypadku wywołań gRPC mechanizm dołączania tokena zależy od języka i frameworka używanego do wywołania. Mechanizm określania tokena w wywołaniu HTTP polega na dodaniu nagłówka Authorization z tokenem okaziciela, którego wartość jest tokenem.
• Zwróć czas wygaśnięcia. Serwer musi zwrócić czas wygaśnięcia tokena, zwykle w sekundach.
• Jeśli musisz utworzyć i podpisać JSON bezpośrednio jako token okaziciela, zamiast używać tokenów dostępu OAuth 2.0, przeczytaj instrukcje dotyczące autoryzacji konta usługi bez OAuth w dokumentacji dla deweloperów Identity.

W przypadku przejazdów na żądanie

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

W przypadku zaplanowanych zadań

• Gdy serwer wywołuje inne interfejsy API, tokeny muszą też zawierać odpowiednią deklarację. W tym celu możesz wykonać te czynności:
  • Ustaw wartość każdego klucza na *.
  • Przyznaj użytkownikowi dostęp do wszystkich taskids i deliveryvehicleids. Aby to zrobić, dodaj dodatkową deklarację w sekcji autoryzacji z kluczami taskid i deliveryvehicleid.
  • Gdy używasz gwiazdki (*) w deklaracji taskids, musi ona być jedynym elementem w tablicy.

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

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

Przykładowy token do operacji w aplikacji kierowcy

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

Przykładowy token do operacji w aplikacji użytkownika

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Przykłady tokenów JWT w przypadku zaplanowanych zadań

W tej sekcji znajdziesz przykłady tokenów JWT w typowych scenariuszach, jeśli korzystasz z zaplanowanych zadań.

Przykładowy token do aplikacji kierowcy

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

Przykładowy token do aplikacji użytkownika

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

Uwaga: Deklaracja trackingid to identyfikator śledzenia dostawy.

Przykłady tokenów JWT w przypadku operacji flotowych

W tej sekcji znajdziesz przykład tokena JWT w typowym scenariuszu operacji flotowych.

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 aplikacji internetowej używanej przez operatora. Uprawnienia wymagane do tych operacji są większe niż w przypadku aplikacji klienckich. Implementację po stronie klienta, która będzie używać tego tokena, znajdziesz w artykule Konfigurowanie biblioteki śledzenia floty w JavaScript:

• Podpisz token za pomocą roli Cloud IAM Fleet Engine Delivery Fleet Reader.

  Uwaga: token utworzony za pomocą tej roli przyznaje niektóre uprawnienia do jednostek Fleet Engine. Upewnij się, że backend udostępnia token tylko uwierzytelnionym użytkownikom.

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

Alternatywna metoda uwierzytelniania operacji serwera backendu

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

Przykładowy token do operacji serwera backendu na żądanie

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

Przykładowy token do operacji serwera backendu zaplanowanej

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

Przykładowy token do operacji serwera backendu zaplanowanej, która tworzy zadania zbiorczo

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

Przykładowy token do operacji serwera backendu zaplanowanej, która dotyczy każdego pojazdu dostawczego

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

Co dalej?

• Sprawdź konfigurację, aby móc utworzyć pojazd testowy i upewnić się, że tokeny działają zgodnie z oczekiwaniami.
• Informacje o używaniu ADC zamiast tokenów JWT w przypadku operacji serwera backendu znajdziesz w artykule Omówienie bezpieczeństwa.