W tym dokumencie znajdziesz informacje o wydawaniu tokenów sieciowych JSON w ramach udostępniania dostępu do danych usługi Fleet Engine aplikacjom internetowym i mobilnym. Jeśli jeszcze tego nie zrobiono, przeczytaj artykuł 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żywanie biblioteki autoryzacji – Google zaleca stosowanie tego podejścia, gdy kod źródłowy jest napisany w języku Java. Ta biblioteka obsługuje wydawanie tokenów JWT w przypadku wszystkich scenariuszy użycia, których możesz potrzebować w usłudze, 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 niezaufanym środowisku, takim jak telefony komórkowe i przeglądarki internetowe, serwer zaplecza 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 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 podpisało 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żywać biblioteki autoryzacji Fleet Engine w Javie, otwórz repozytorium GitHub. Biblioteka upraszcza tworzenie tokenów JWT Fleet Engine i zabezpiecza je. Umożliwia:
- Deklaracje zależności projektu
- pełna lista wszystkich ról na koncie usługi w przypadku przejazdów na żądanie lub zaplanowanych zadań;
- mechanizmy podpisywania tokenów inne niż korzystanie z plików danych logowania, takie jak podszywanie się pod konto usługi;
- Dołącza podpisane tokeny do żądań wychodzących wysyłanych z gRPC stub lub biblioteki klienta Google API Codegen (GAPIC).
- Instrukcje integrowania podpisujących z bibliotekami klienta Fleet Engine
Jeśli tokeny JWT są generowane przez Twój kod
Jeśli nie możesz użyć biblioteki autoryzacji dla Javy, musisz zaimplementować tokeny JWT w swojej bazie kodu. W tej sekcji znajdziesz kilka wskazówek dotyczących tworzenia własnych tokenów. Aby uzyskać listę pól i deklaracji JWT, przejdź do sekcji Tokeny internetowe JSON w sekcji Bezpieczeństwo w Fleet Engine. Informacje o rolach konta usługi używanych przez Fleet Engine znajdziesz w sekcji 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żywaj odpowiednich kont usługi i ról. Konto usługi i powiązana rola zapewniają, że użytkownik żądający tokena 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, do których nie powinno mieć dostępu.
- Jeśli podpisywanie tokena JWT ma służyć 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 ramy, których użyto do wywołania. Mechanizmem określania tokena w wywołaniu HTTP jest dołączenie nagłówka
Authorizationz tokenem uprawnień, którego wartość to token. - Zwraca czas ważności. Serwer musi zwrócić czas ważności tokena, zwykle w sekundach.
- Jeśli chcesz utworzyć i podpisać plik JSON bezpośrednio jako posiadacz tokena, 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 usługi Identity.
W przypadku przejazdów na żądanie
- Podczas tworzenia ładunku JWT dodaj w sekcji autoryzacji dodatkowy element z kluczem
vehicleidlubtripidustawionym na wartość identyfikatora pojazdu lub identyfikatora podróży, do której odnosi się wywołanie.
Zaplanowane zadania
- Gdy serwer wywołuje inne interfejsy API, tokeny muszą też zawierać odpowiednie roszczenie. Aby to zrobić, wykonaj te czynności:
- Ustaw wartość każdego klucza na
*. - Przyznaj użytkownikowi dostęp do wszystkich
taskidsideliveryvehicleids. Aby to zrobić, dodaj w sekcji autoryzacji dodatkowy element żądania z kluczamitaskidideliveryvehicleid. - Jeśli używasz gwiazdki (
*) w oświadczeniutaskids, musi to być jedyny element w tablicy.
- Ustaw wartość każdego klucza na
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 aplikacji dla kierowcy
{
"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 w przypadku zadań zaplanowanych
Ta sekcja zawiera przykład tokena JWT na potrzeby typowych scenariuszy, jeśli używasz zaplanowanych zadań.
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 dla typowego scenariusza w operacjach floty.
Przykładowy token do śledzenia wszystkich zadań i pojazdów we flocie
Przykładowy token, który śledzi wszystkie zadania i pojazdy w flotach z aplikacji internetowej używanej przez operatora. Uprawnienia wymagane do tych operacji są bardziej restrykcyjne niż w przypadku aplikacji klienckich. Aby dowiedzieć się, jak zaimplementować tę funkcję po stronie klienta, która będzie używać tego tokena, zapoznaj się z artykułem Konfigurowanie JavaScript Fleet Tracking Library.
Podpisz token przy użyciu roli
Fleet Engine Delivery Fleet Readerw 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 dla zaplanowanego działania serwera backendu na potrzeby pojazdu dostawczego
{
"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?
- Sprawdź konfigurację, aby utworzyć pojazd próbny i upewnić się, że tokeny działają prawidłowo.
- Informacje o używaniu ADC zamiast tokenów JWT do operacji na serwerze zaplecza znajdziesz w artykule Omówienie zabezpieczeń.