Uwierzytelnianie i autoryzacja

W tej sekcji omawiamy pojęcia uwierzytelniania i autoryzacji z uwzględnieniem implementacji Fleet Engine. Znajdziesz w nim szczegółowe informacje o procedurach, które musisz wykonać, aby zabezpieczyć wywołania funkcji Fleet Engine.

Funkcje udostępniane przez usługę Last Mile Fleet Solution można skonfigurować w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON (JWT) podpisanych przy użyciu kont usługi utworzonych w Cloud Console.

Opis

W ramach mechanizmu autoryzacji Fleet Engine zapewnia dodatkowe zabezpieczenia związane z wywołaniami pochodzącymi ze środowisk o niskim poziomie zaufania. Środowiska o niskim poziomie zaufania to m.in. smartfony i przeglądarki. Dodatkowo Fleet Engine stosuje zasadę jak najmniejszych uprawnień, zgodnie z którą wywołanie powinno mieć tylko te uprawnienia, które są niezbędne do wykonania zadania.

Aby chronić wywołania funkcji pochodzące ze środowisk o niskim zaufaniu, zaprojektowaliśmy mechanizm, w którym Twój kod tworzy token na serwerze backendu, czyli środowisku w pełni zaufanej. Każde wywołanie zawiera pełny opis zabezpieczeń, który jest następnie zaszyfrowany w tokenie JWT przekazywanym przy użyciu wywołania z dowolnego środowiska.

Zasady projektowania uwierzytelniania

Proces uwierzytelniania Fleet Engine wykorzystuje poniższe zasady projektowania.

  • Role uprawnień określają zakres dozwolonych działań elementu wywołującego. Na przykład rola SuperUser może wykonywać wszystkie czynności, a rola SuperUser może wprowadzać tylko minimalną liczbę aktualizacji lokalizacji.

  • Role uprawnień są powiązane z kontami usługi.

  • Żądania JWT jeszcze bardziej ograniczają encje, na których może działać element wywołujący. Mogą to być określone zadania lub pojazdy dostawcze.

  • Żądania wysyłane do Fleet Engine zawsze zawierają token JWT.

    • Tokeny JWT są powiązane z kontami usługi, dlatego żądania wysłane do Fleet Engine są niejawnie powiązane z kontem usługi powiązanym z tokenem JWT.
  • Aby zażądać odpowiedniego tokena JWT, który możesz następnie przekazać do Fleet Engine, Twój kod działający w środowisku o niskim poziomie zaufania musi najpierw wywołać kod działający w środowisku w pełni zaufanym.

  • Fleet Engine wykonuje następujące testy zabezpieczeń:

    1. Role uprawnień powiązane z kontem usługi zapewniają prawidłową autoryzację elementu wywołującego wywoływanie interfejsu API.

    2. Żądania JWT przekazane w żądaniu zapewniają prawidłową autoryzację elementu wywołującego do operacji na encji.

Przebieg uwierzytelniania

Poniższy diagram sekwencji przedstawia szczegóły przepływu uwierzytelniania.

  1. Administrator floty tworzy konta usługi.

  2. Administrator floty przypisuje określone role uprawnień do kont usługi.

  3. Administrator floty konfiguruje backend przy użyciu kont usługi.

  4. Aplikacja kliencka żąda tokena JWT z backendu partnera. Może to być aplikacja kierowcy, aplikacja dla klientów indywidualnych lub aplikacja do monitorowania.

  5. Fleet Engine wydaje token JWT dla odpowiedniego konta usługi. Aplikacja kliencka otrzymuje token JWT.

  6. Aplikacja klienta używa tokena JWT, aby połączyć się z Fleet Engine, aby odczytywać lub modyfikować dane w zależności od ról uprawnień przypisanych do niej na etapie konfiguracji.

Diagram sekwencji uwierzytelniania

Konfiguracja projektu Cloud

Aby skonfigurować projekt w chmurze, najpierw utwórz go, a potem utwórz konta usługi.

Aby utworzyć projekt Google Cloud:

  1. Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
  2. Za pomocą panelu interfejsów API i usług włącz interfejs Local Rides and Deliveries API.

Konta usługi i role uprawnień

Konto usługi to specjalne konto używane przez aplikację, a nie osobę. Zwykle konto usługi służy do generowania tokenów JWT, które przyznają różne zestawy uprawnień w zależności od roli. Aby zmniejszyć ryzyko nadużyć, możesz utworzyć wiele kont usługi z minimalnym zestawem ról.

Rozwiązanie Last Mile Fleet Solution wykorzystuje te role:

RolaOpis
Użytkownik zaufanego sterownika Fleet Engine Delivery

roles/fleetengine.deliveryTrustedDriver
Przyznaje uprawnienia do tworzenia i aktualizowania pojazdów dostawczych oraz zadań, w tym do aktualizowania lokalizacji pojazdu dostawczego oraz stanu lub wyniku zadania. Tokeny generowane przez konto usługi o tej roli są zwykle używane z urządzeń mobilnych kierowcy dostawcy lub z serwerów backendu.
Użytkownik niezaufanego sterownika Fleet Engine Delivery

roles/fleetengine.deliveryUntrustedDriver
Przyznaje uprawnienia do aktualizowania lokalizacji pojazdu dostawczego. Tokeny generowane przez konto usługi z tą rolą są zwykle używane z urządzeń mobilnych kierowcy dostawcy.
Użytkownik indywidualny Fleet Engine Delivery

roles/fleetengine.deliveryConsumer
Przyznaje uprawnienia do wyszukiwania zadań przy użyciu identyfikatora śledzenia oraz do odczytywania informacji o zadaniach, ale bez ich aktualizowania. Tokeny generowane przez konto usługi o tej roli są zwykle używane z przeglądarki internetowej konsumenta dostarczającego dane.
Superużytkownik Fleet Engine Delivery

roles/fleetengine.deliverySuperUser
Przyznaje uprawnienia do wszystkich interfejsów API pojazdów i zadań. Tokeny generowane przez konto usługi z tą rolą są zwykle używane z serwerów backendu.
Odczytujący informacje o flocie Fleet Engine Delivery

roles/fleetengine.deliveryFleetReader
Przyznaje uprawnienia do odczytu pojazdów dostawczych i zadań oraz do wyszukiwania zadań za pomocą identyfikatora śledzenia. Tokeny generowane przez konto usługi o tej roli są zwykle używane z przeglądarki internetowej operatora floty dostarczania.

Organizacje, które dostarczają im urządzenia zarządzane przez firmowe systemy IT, mogą korzystać z elastyczności, jaką daje rola zaufanego użytkownika Fleet Engine, i zdecydować się na integrację niektórych lub wszystkich interakcji Fleet Engine z aplikacją mobilną.

Organizacje obsługujące zasady „Przynieś własne urządzenia” powinny wybrać bezpieczeństwo roli „Niezaufany kierowca Fleet Engine” i korzystać tylko z aplikacji mobilnej do wysyłania aktualizacji lokalizacji pojazdu do Fleet Engine. Wszystkie pozostałe interakcje powinny pochodzić z serwerów backendu klienta.

Pakiety SDK sterowników i konsumenta opierają się na tych standardowych rolach. Możesz jednak tworzyć role niestandardowe, które pozwalają łączyć dowolny zestaw uprawnień. Jeśli brakuje wymaganego uprawnienia, pakiety SDK sterownika i pakietu SDK dla klientów indywidualnych będą wyświetlać komunikaty o błędach. Dlatego zdecydowanie zalecamy używanie przedstawionego powyżej standardowego zestawu ról zamiast ról niestandardowych.

Tworzenie konta usługi

Konto usługi możesz utworzyć na karcie IAM & Admin > Service Accounts w konsoli Google Cloud. Z listy Rola wybierz Fleet Engine i przypisz jedną z ról do konta usługi. Warto wskazać konto powiązane z poszczególnymi rolami. Na przykład nadaj kontu usługi rozpoznawalną nazwę.

Jeśli chcesz generować tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi umożliwia ich generowanie tokenów za pomocą narzędzi wiersza poleceń gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Gdzie my-user@example.com to adres e-mail używany do uwierzytelniania w gcloud (gcloud auth list --format='value(account)').

Biblioteka uwierzytelniania Fleet Engine

Fleet Engine używa tokenów JWT, aby ograniczyć dostęp do interfejsów API Fleet Engine. Nowa biblioteka uwierzytelniania Fleet Engine, dostępna na GitHubie, upraszcza tworzenie tokenów JWT Fleet Engine i bezpiecznie je podpisuje.

Biblioteka zapewnia te korzyści:

  • Upraszcza proces tworzenia tokenów Fleet Engine.
  • Udostępnia mechanizmy podpisywania tokenów inne niż pliki danych logowania (np. podszywanie się pod konto usługi).
  • Dołącza podpisane tokeny do żądań wychodzących wysyłanych z odcinka gRPC lub klienta GAPIC.

Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji

Jeśli nie używasz biblioteki uwierzytelniania Fleet Engine, tokeny JWT musisz utworzyć bezpośrednio w bazie kodu. Wymaga to dogłębnej wiedzy na temat tokenów JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.

W Fleet Engine tokeny JWT umożliwiają krótkotrwałe uwierzytelnianie i umożliwiają urządzeniom modyfikowanie tylko pojazdów lub zadań, do których są autoryzowane. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera informacje takie jak klucz prywatny do użycia (uzyskany z kont usługi) i algorytm szyfrowania. Sekcja roszczenia zawiera takie informacje jak czas utworzenia tokena, czas życia tokena, usługi, do których token zgłasza prawa dostępu, i inne informacje autoryzacji umożliwiające zakres dostępu, na przykład identyfikator pojazdu dostawczego.

Sekcja nagłówka JWT zawiera te pola:

PoleOpis
alg Algorytm, który ma zostać użyty. „RS256”.
typ Typ tokena. JWT.
dziecko Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` pliku JSON konta usługi. Pamiętaj, aby użyć klucza z konta usługi z odpowiednim poziomem uprawnień.

Sekcja deklaracji JWT zawiera te pola:

PoleOpis
iss Adres e-mail konta usługi.
zast. Adres e-mail konta usługi.
j.a. SERVICE_NAME konta usługi, w tym przypadku https://fleetengine.googleapis.com/
Iat Sygnatura czasowa utworzenia tokena wyrażona w sekundach, które upłynęły od godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Odczekaj 10 minut, aż się przechyli. Jeśli sygnatura czasowa przypada w przeszłości lub w przyszłości, serwer może zgłosić błąd.
exp Sygnatura czasowa wygaśnięcia tokena podana w sekundach, które upłynęły od godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Żądanie nie powiedzie się, jeśli sygnatura czasowa wybiega za więcej niż godzinę.
autoryzacja W zależności od przypadku użycia może zawierać parametry `deliveryvehicleid`, `trackingid`, `taskid` lub `taskids`.

Wygenerowanie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz w sekcji Autoryzacja konta usługi bez OAuth. Potem możesz dołączyć wygenerowany token do wywołań gRPC lub innych metod używanych do uzyskiwania dostępu do Fleet Engine.

deklaracje JWT

Rozwiązanie Last Mile Fleet Solution wykorzystuje roszczenia prywatne. Użycie prywatnych deklaracji daje pewność, że tylko autoryzowani klienci mają dostęp do swoich danych. Jeśli na przykład backend generuje token sieciowy JSON dla urządzenia mobilnego kierowcy, token ten powinien zawierać żądanie deliveryvehicleid z wartością identyfikatora pojazdu dostawczego tego kierowcy. Następnie, w zależności od roli kierowcy, tokeny umożliwiają dostęp tylko w przypadku określonego identyfikatora pojazdu dostarczającego, a nie żadnego innego dowolnego identyfikatora pojazdu.

Rozwiązanie Last Mile Fleet Solution opiera się na następujących roszczeniach prywatnych:

  • deliveryvehicleid – użyj przy wywoływaniu interfejsów API pojazdów w momencie dostawy.
  • taskid – użyj podczas wywoływania interfejsów API dla poszczególnych zadań.
  • taskids – użyj, gdy dzwonisz pod numer BatchCreateTasksAPI. To żądanie musi mieć formę tablicy, a tablica powinna zawierać wszystkie identyfikatory zadań niezbędne do zrealizowania żądania. Nie uwzględniaj roszczeń delivervehicleid, trackingid ani taskid.
  • trackingid – użyj podczas wywoływania: SearchTasksAPI. Roszczenie musi pasować do identyfikatora śledzenia w żądaniu. Nie uwzględnij roszczeń delivervehicleid, taskid ani taskids.

Token musi też zawierać odpowiednie żądanie, gdy wywołujesz interfejsy API z serwera backendu, ale możesz użyć wartości specjalnej gwiazdki („*”) w żądaniach deliveryvehicleid, taskid i trackingid. Gwiazdki („*”) można też użyć w żądaniu taskids, ale musi ona być jedynym elementem w tablicy.

Jeśli chcesz utworzyć i podpisać plik JSON bezpośrednio jako nośnik tokena, a nie używać tokenów dostępu OAuth 2.0, zapoznaj się z instrukcjami autoryzacji kont usługi bez protokołu OAuth w dokumentacji dla programistów tożsamości.

Sposób dołączania tokena do wywołania gRPC zależy od języka i platformy użytej do wywołania. Mechanizmem określania tokena dla wywołania HTTP jest uwzględnienie nagłówka Authorization z tokenem okaziciela, którego wartość jest tokenem, jak zaznaczono w uwagach do autoryzacji poszczególnych przypadków użycia śledzenia przesyłek lub wydajności floty.

Poniższy przykład przedstawia token operacji na poziomie zadania z serwera 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": "*"
       }
    }

Poniższy przykład przedstawia token 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": ["*"]
       }
    }

Poniższy przykład pokazuje token operacji na pojazdach dostawczych z serwera 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": {
         "deliveryvehicleid": "*"
       }
    }

Poniższy przykład pokazuje token dla klientów będących użytkownikami:

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

Poniższy przykład pokazuje token aplikacji sterownika:

    {
      "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"
       }
    }
  • W polu kid w nagłówku podaj identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu private_key_id pliku JSON konta usługi.
  • W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email pliku JSON konta usługi.
  • W polu aud podaj https://SERVICE_NAME/.
  • W polu iat podaj sygnaturę czasową utworzenia tokena w sekundach, które upłynęły od godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Odczekaj 10 minut, aby zmienić zniekształcenie. Jeśli sygnatura czasowa przypada w przeszłości lub w przyszłości, serwer może zgłosić błąd.
  • W polu exp podaj sygnaturę czasową wygaśnięcia tokena w sekundach od godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Zalecana wartość to iat + 3600.

Podczas podpisywania tokena, który ma być przekazany do urządzenia mobilnego lub użytkownika, użyj pliku danych logowania w roli Kierowca lub konsument. W przeciwnym razie urządzenie mobilne lub użytkownik będzie mógł zmieniać lub wyświetlać informacje, do których nie powinien mieć dostępu.