W tym dokumencie opisujemy, jak wydawać tokeny sieciowe JSON w ramach umożliwiania aplikacjom internetowym i mobilnym dostępu do danych Fleet Engine. Jeśli jeszcze nie znasz tych informacji, przeczytaj artykuł Tokeny sieciowe JSON w sekcji Bezpieczeństwo we Fleet Engine. W usłudze Fleet Engine możesz generować tokeny JWT na jeden z tych sposobów:
- Użycie biblioteki autoryzacji – Google zaleca to podejście, jeśli baza kodu jest napisana w języku Java. Ta biblioteka obsługuje wydawanie tokenów JWT we wszystkich przypadkach użycia, które mogą być potrzebne w usłudze, i znacznie upraszcza implementację.
- Tworzenie własnych tokenów JWT – jeśli nie możesz używać naszej biblioteki JWT, musisz utworzyć te tokeny we własnej bazie kodu. Ta sekcja zawiera różne przykłady tokenów JWT dla każdego scenariusza.
Jak działają tokeny JWT
W przypadku niezaufanych środowisk, takich jak telefony komórkowe i przeglądarki, 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 zaufaniu, aby poprosić o odpowiedni token 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.
Oświadczenia JWT dodatkowo ograniczają zasoby, na których klient może wykonywać operacje, takie jak konkretne pojazdy, przejazdy czy zadania.
Używanie biblioteki autoryzacji dla Javy
Aby używać biblioteki autoryzacji Fleet Engine dla Javy, odwiedź repozytorium GitHub. Biblioteka upraszcza tworzenie tokenów JWT Fleet Engine i bezpiecznie je podpisuje. Zapewnia:
- Deklaracje zależności projektu
- Pełna lista wszystkich ról kont usługi w przypadku przejazdów na żądanie lub zaplanowanych zadań
- mechanizmy podpisywania tokenów inne niż używanie plików danych logowania, takie jak personifikacja konta usługi;
- dołącza podpisane tokeny do żądań wychodzących wysyłanych z kodu pośredniczącego gRPC lub biblioteki klienta Google API Codegen (GAPIC);
- Instrukcje dotyczące integracji podpisujących z bibliotekami klienta Fleet Engine
Jeśli generujesz tokeny JWT z kodu
Jeśli nie możesz użyć biblioteki autoryzacji dla Javy, musisz zaimplementować tokeny JWT we własnej 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 artykule Bezpieczeństwo we Fleet Engine. Informacje o rolach kont usługi używanych przez Fleet Engine znajdziesz w artykule Role kont usługi. W następnej sekcji znajdziesz listę przykładów tokenów JWT dla 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 z nim rola zapewniają, że użytkownik żądający tokena ma uprawnienia do wyświetlania informacji, do których token daje 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 dla roli pakietu SDK kierowcy lub konsumenta. W przeciwnym razie urządzenie mobilne może zmieniać dane, do których nie powinno mieć dostępu, i uzyskiwać do nich dostęp.
- Jeśli podpisujesz token JWT, który ma być używany do wywołań uprzywilejowanych, 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żytych do utworzenia tokenów.
- W przypadku wywołań gRPC mechanizm dołączania tokena zależy od języka i platformy użytych do wykonania wywołania. Mechanizm określania tokena dla wywołania HTTP polega na dołączeniu nagłówka
Authorizationz tokenem na okaziciela, którego wartością jest token. - Zwróć czas wygaśnięcia. Serwer musi zwrócić czas wygaśnięcia tokena, zwykle w sekundach.
- Jeśli musisz utworzyć i podpisać obiekt JSON bezpośrednio jako posiadacz tokena, a nie używać tokenów dostępu OAuth 2.0, zapoznaj się z instrukcjami dotyczącymi autoryzacji konta usługi bez protokołu OAuth w dokumentacji dla deweloperów dotyczącej tożsamości.
Przejazdy na żądanie
- Podczas tworzenia ładunku JWT dodaj dodatkowe oświadczenie w sekcji autoryzacji z kluczem
vehicleidlubtripidustawionym na wartość identyfikatora pojazdu lub identyfikatora przejazdu, dla którego jest wykonywane wywołanie.
Zaplanowane zadania
- Gdy serwer wywołuje inne interfejsy API, tokeny muszą też zawierać odpowiednie oświadczenie. Aby to zrobić, możesz wykonać te czynności:
- Ustaw wartość każdego klucza na
*. - Przyznaj użytkownikowi dostęp do wszystkich
taskidsideliveryvehicleids. Aby to zrobić, dodaj dodatkowe oświadczenie w sekcji autoryzacji z kluczamitaskidideliveryvehicleid. - Jeśli w deklaracji
taskidsużywasz gwiazdki (*), musi to być jedyny element w tablicy.
- Ustaw wartość każdego klucza na
Przykłady tokenów JWT dla przejazdów na żądanie
W tej sekcji znajdziesz przykłady tokenów JWT dla typowych scenariuszy, jeśli korzystasz z przejazdów na żądanie.
Przykładowy token operacji aplikacji dla kierowców
{
"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 użytkownika
{
"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 JWT dla zaplanowanych zadań
W tej sekcji znajdziesz przykłady tokenów JWT dla typowych scenariuszy, jeśli używasz zaplanowanych zadań.
Przykładowy token dla aplikacji dla kierowców
{
"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 aplikacji użytkownika
{
"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 JWT dotyczące operacji na flocie
W tej sekcji znajdziesz przykładowy token JWT dla typowego scenariusza operacji floty.
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 wykonania tych operacji są większe niż w przypadku aplikacji klienckich. Zobacz Konfigurowanie biblioteki JavaScript do śledzenia floty, aby dowiedzieć się, jak zaimplementować po stronie klienta rozwiązanie, które będzie używać tego tokena:
Podpisz token za pomocą roli
Fleet Engine Delivery Fleet ReaderCloud 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 na potrzeby operacji na serwerze backendu
Google zaleca używanie domyślnych danych uwierzytelniających aplikacji do uwierzytelniania operacji na serwerze 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 operacji na serwerze 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 zaplanowanej operacji 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": { "taskid": "*" } }
Przykładowy token zaplanowanej operacji zbiorczego tworzenia zadań 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 zaplanowanej operacji na serwerze backendu dla 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ą zgodnie z oczekiwaniami.
- Informacje o używaniu domyślnych danych uwierzytelniających aplikacji zamiast tokenów JWT do operacji na serwerze backendu znajdziesz w omówieniu zabezpieczeń.