Uwierzytelnianie i autoryzacja

W tej sekcji omawiamy pojęcia uwierzytelniania i autoryzacji z uwzględnieniem implementacji Fleet Engine. Szczegółowy opis procedur, które musisz wykonać, aby zabezpieczyć wywołania funkcji Fleet Engine.

Funkcje udostępniane przez usługę Last Mile Fleet Solution możesz skonfigurować w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON (JWT), które zostały podpisane za pomocą kont usługi utworzonych w Cloud Console.

Przegląd

W ramach mechanizmu autoryzacji Fleet Engine zapewnia dodatkowe zabezpieczenia przed wywołaniami pochodzącymi ze środowisk o niskim zaufaniu. Środowiska o niskim zaufaniu to m.in. smartfony i przeglądarki. Dodatkowo Fleet Engine stosuje zasadę jak najmniejszych uprawnień, zgodnie z którą wywołanie powinno mieć przypisane 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, który jest środowiskiem w pełni zaufanym. Każde wywołanie zawiera pełny opis zabezpieczeń, który jest następnie szyfrowany w tokenie JWT przekazywanym z wywołaniem z dowolnego środowiska.

Zasady projektowania uwierzytelniania

Przepływ uwierzytelniania Fleet Engine obejmuje poniższe zasady projektowania.

  • Role uprawnień określają zakres dozwolonej aktywności elementu wywołującego. Na przykład rola SuperUser może wykonywać wszystkie czynności, a SuperUser może wprowadzać tylko aktualizacje lokalizacji.

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

  • deklaracje 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 wysył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, kod działający w środowisku o niskim zaufaniu musi najpierw wywołać kod działający w całkowicie zaufanym środowisku.

  • Fleet Engine wykonuje te kontrole zabezpieczeń:

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

    2. Deklaracje JWT przekazane w żądaniu zapewniają prawidłową autoryzację elementu wywołującego do działania w elemencie.

Proces uwierzytelniania

Na diagramie poniżej widać te 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 z kontami usługi.

  4. Aplikacja kliencka żąda tokena JWT z backendu partnera. Wnioskiem może być kierowca, aplikacja Consumer lub aplikacja do monitorowania.

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

  6. Aplikacja kliencka używa tokena JWT do łączenia się z Fleet Engine w celu odczytywania lub modyfikowania danych w zależności od ról uprawnień przypisanych do niej na etapie konfiguracji.

Diagram sekwencji uwierzytelniania

Konfigurowanie projektu w chmurze

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

Aby utworzyć projekt Google Cloud:

  1. Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
  2. Korzystając z 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 do tworzenia tokenów JWT, które przyznają różne zestawy uprawnień w zależności od roli, używane jest konto usługi. Aby zmniejszyć ryzyko nadużyć, możesz utworzyć kilka kont usługi o minimalnym zestawie ról.

Rozwiązanie ostatniej mili:

RolaOpis
Użytkownik zaufanego sterownika Fleet Engine Delivery

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

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

roles/fleetengine.deliveryConsumer		 Daje uprawnienie do wyszukiwania zadań przy użyciu identyfikatora śledzenia oraz do odczytywania informacji o zadaniach, ale nie do ich aktualizowania. Tokeny wydobywane przez konto usługi z tą rolą 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 zadań i pojazdów dostawczych. Tokeny wydobywane 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		 Daje uprawnienie do odczytu pojazdów i zadań dostawy oraz do wyszukiwania zadań za pomocą identyfikatora śledzenia. Tokeny wydobywane przez konto usługi o tej roli są zwykle używane w przeglądarce internetowej operatora floty dostarczania.

Organizacje, które dostarczają dostawcom urządzenia zarządzane przez firmowych działów IT, mogą skorzystać z elastyczności, jaką daje rola zaufanego użytkownika Fleet Engine, i zintegrować niektóre lub wszystkie interakcje Fleet Engine z aplikacją mobilną.

Organizacje, które obsługują zasady korzystania z urządzenia mobilnego, powinny uwzględniać bezpieczeństwo roli „niezaufany kierowca” we Fleet Engine i korzystać z aplikacji mobilnej do wysyłania aktualizacji lokalizacji pojazdu do Fleet Engine. Wszystkie pozostałe interakcje powinny pochodzić z serwerów backendu klienta.

Na podstawie tych standardowych ról powstają pakiety SDK sterowników i konsumentów. Można jednak tworzyć role niestandardowe, które umożliwiają łączenie ze sobą dowolnego zestawu uprawnień. Jeśli brakuje wymaganego uprawnienia, pakiety SDK sterowników i konsumenta wyświetlają 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. Dobrym pomysłem jest wskazywanie konta, które jest powiązane z daną rolą. Na przykład nadaj kontu usługi rozpoznawalną nazwę.

Jeśli musisz tworzyć tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi umożliwia im tworzenie 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 za pomocą gcloud (gcloud auth list --format='value(account)').

Biblioteka uwierzytelniania Fleet Engine

Fleet Engine używa tokenów JWT do ograniczenia dostępu do interfejsów API Fleet Engine. Nowa biblioteka uwierzytelniania Fleet Engine dostępna w GitHub 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ż korzystanie z plików 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 trzeba 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 zapewniają krótkotrwałe uwierzytelnianie i dają pewność, że urządzenia mogą modyfikować tylko pojazdy lub zadania, do których są autoryzowane. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera takie informacje, jak klucz prywatny do użycia (uzyskany z kont usługi) i algorytm szyfrowania. Sekcja deklaracji zawiera takie informacje jak czas utworzenia tokena, czas życia tokena, usługi, do których token żąda dostępu, oraz inne informacje autoryzacji pozwalające ograniczyć dostęp, np. identyfikator pojazdu dostawczego.

Sekcja nagłówka JWT zawiera te pola:

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

Sekcja deklaracji JWT zawiera te pola:

PoleOpis
IS Adres e-mail Twojego konta usługi.
zast. Adres e-mail Twojego konta usługi.
śr. SERVICE_NAME (SERVICE_NAME) Twojego konta usługi, w tym przypadku https://fleetengine.googleapis.com/
IAT Sygnatura czasowa utworzenia tokena podana w sekundach, które upłynęły od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Poczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa przypada w zbyt odległej 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 r. Żądanie nie powiedzie się, jeśli sygnatura czasowa przypada za więcej niż godzinę.
autoryzacja W zależności od przypadku użycia może zawierać parametr „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 artykule 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.

Żądania JWT

Rozwiązanie Last Mile Fleet Solution korzysta z roszczeń prywatnych. Korzystanie z deklaracji prywatnych daje pewność, że tylko autoryzowani klienci mają dostęp do własnych danych. Jeśli na przykład Twój backend generuje token sieciowy JSON dla urządzenia mobilnego kierowcy, token ten powinien zawierać deklarację deliveryvehicleid z wartością identyfikatora pojazdu dostarczającego tego kierowcy. Następnie, w zależności od roli kierowcy, tokeny umożliwiają dostęp tylko do konkretnego identyfikatora pojazdu dostarczającego, a nie do żadnego innego dowolnego identyfikatora pojazdu.

Rozwiązanie Last Mile Fleet Solution wykorzystuje te prywatne deklaracje:

  • deliveryvehicleid – użyj w przypadku wywoływania interfejsów API pojazdów w zależności od dostawy.
  • taskid – używaj w przypadku wywoływania interfejsów API do poszczególnych zadań.
  • taskids – użyj, gdy dzwonisz pod numer BatchCreateTasksAPI. Deklaracja musi mieć postać tablicy, a tablica powinna zawierać wszystkie identyfikatory zadań niezbędne do zrealizowania żądania. Nie uwzględniaj roszczeń delivervehicleid, trackingid ani taskid.
  • trackingid – użyj, gdy wywołujesz SearchTasksAPI. Deklaracja musi pasować do identyfikatora śledzenia w żądaniu. Nie uwzględniaj roszczeń delivervehicleid, taskid ani taskids.

Token musi też zawierać odpowiednią deklarację podczas wywoływania interfejsów API z serwera backendu, ale możesz użyć specjalnej wartości gwiazdki („*”) w deklaracjach deliveryvehicleid, taskid i trackingid. Gwiazdki można również użyć w żądaniu taskids, ale musi to być jedyny element tablicy.

Jeśli chcesz utworzyć i podpisać plik JSON bezpośrednio jako nośnik tokena zamiast używać tokenów dostępu OAuth 2.0, zapoznaj się z instrukcjami autoryzowania konta usługi bez OAuth w dokumentacji Identity Developer.

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 dołączenie nagłówka Authorization z tokenem okaziciela, którego wartość jest tokenem. Opisaliśmy to w uwagach do autoryzacji poszczególnych przypadków użycia śledzenia przesyłek lub wydajności floty.

Poniższy przykład przedstawia token z serwera backendu dla operacji wykonywania poszczególnych zadań:

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

W przykładzie poniżej znajdziesz token z serwera backendu na potrzeby operacji na pojazdach dostawczych:

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

Oto przykład tokena 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"
       }
    }

Ten przykład przedstawia 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 w pliku JSON konta usługi.
  • W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email w 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 00:00:00 czasu UTC 1 stycznia 1970 r.). Poczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa przypada w zbyt odległej 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 godz. 00:00:00 czasu UTC 1 stycznia 1970 r. Zalecana wartość to iat + 3600.

Podczas podpisywania tokena, który ma zostać przekazany na urządzenie mobilne lub użytkownika, użyj pliku danych logowania dla roli Kierowca lub Konsument. W przeciwnym razie urządzenie mobilne lub użytkownik będą mogli zmieniać lub wyświetlać informacje, do których nie powinni mieć dostępu.