Аутентификация и авторизация

В этом разделе объясняются концепции аутентификации и авторизации применительно к реализации Fleet Engine. В нем подробно описаны процедуры, которые необходимо выполнить для защиты вызовов функций Fleet Engine.

Вы можете настроить возможности, предоставляемые Last Mile Fleet Solution, через Google Cloud Console . Эти API и SDK требуют использования веб-токенов JSON (JWT), подписанных с использованием сервисных учетных записей, созданных в Cloud Console.

Обзор

В рамках своего механизма авторизации Fleet Engine обеспечивает дополнительную защиту от вызовов, исходящих из сред с низким уровнем доверия. К средам с низким уровнем доверия относятся смартфоны и браузеры. Кроме того, Fleet Engine использует принцип наименьших привилегий , согласно которому вызову должны быть предоставлены только те привилегии, которые необходимы для выполнения его задачи.

Чтобы защитить вызовы функций, исходящие из сред с низким уровнем доверия, Google разработал механизм, в котором ваш код создает токен на вашем внутреннем сервере, который является полностью доверенной средой. Каждый вызов содержит полное описание безопасности, которое затем шифруется в JWT, который вы передаете вместе с вызовом из любой среды.

Принципы разработки аутентификации

Процесс аутентификации Fleet Engine включает в себя следующие принципы проектирования.

  • Роли IAM определяют объем разрешенной активности вызывающего абонента. Например, роли SuperUser разрешено делать все, тогда как роли Untrusted Driver разрешено выполнять только минимальные обновления местоположения.

  • Роли IAM связаны с учетными записями служб.

  • Заявления JWT дополнительно ограничивают объекты, с которыми может работать вызывающая сторона. Это могут быть конкретные задачи или средства доставки.

  • Запросы, отправляемые в Fleet Engine, всегда содержат JWT.

    • Поскольку JWT связаны с учетными записями служб, запросы, отправляемые в Fleet Engine, неявно связаны с учетной записью службы, связанной с JWT.

  • Чтобы запросить соответствующий JWT, который затем можно передать в Fleet Engine, ваш код, работающий в среде с низким уровнем доверия, должен сначала вызвать ваш код, работающий в полностью доверенной среде.

  • Fleet Engine выполняет следующие проверки безопасности:

    1. Роли IAM, связанные с учетной записью службы, обеспечивают правильную авторизацию вызывающей стороны для выполнения вызова API.

    2. Утверждения JWT, переданные в запросе, предоставляют вызывающей стороне правильное разрешение на работу с сущностью.

Поток аутентификации

Следующая диаграмма последовательности демонстрирует детали процесса аутентификации.

  1. Администратор автопарка создает сервисные учетные записи.

  2. Администратор автопарка назначает определенные роли IAM сервисным учетным записям.

  3. Администратор автопарка настраивает свою серверную часть с помощью сервисных учетных записей.

  4. Клиентское приложение запрашивает JWT у серверной части партнера. Запрашивающим может быть приложение «Драйвер», приложение «Потребитель» или приложение для мониторинга.

  5. Fleet Engine выдает JWT для соответствующей учетной записи службы. Клиентское приложение получает JWT.

  6. Клиентское приложение использует JWT для подключения к Fleet Engine для чтения или изменения данных в зависимости от ролей IAM, назначенных ему на этапе установки.

Схема последовательности аутентификации

Настройка облачного проекта

Чтобы настроить облачный проект, сначала создайте проект, а затем создайте учетные записи служб.

Чтобы создать проект Google Cloud:

  1. Создайте проект Google Cloud с помощью Google Cloud Console.
  2. Используя панель API и служб, включите API местных поездок и доставок.

Учетные записи служб и роли IAM

Сервисная учетная запись — это особый вид учетной записи, которая используется приложением, а не человеком. Обычно учетная запись службы используется для создания JWT, которые предоставляют разные наборы разрешений в зависимости от роли. Чтобы уменьшить вероятность злоупотреблений, вы можете создать несколько учетных записей служб, каждая из которых имеет минимальный набор необходимых ролей.

Last Mile Fleet Solution использует следующие роли:

Роль Описание
Доверенный водитель Fleet Engine Delivery

roles/fleetengine.deliveryTrustedDriver		 Предоставляет разрешение на создание и обновление средств доставки и задач, включая обновление местоположения средства доставки, а также статуса или результата задачи. Токены, созданные сервисным аккаунтом с этой ролью, обычно используются с мобильных устройств вашего водителя доставки или с ваших внутренних серверов.
Недоверенный водитель-пользователь Fleet Engine Delivery

roles/fleetengine.deliveryUntrustedDriver		 Предоставляет разрешение на обновление местоположения средства доставки. Токены, созданные сервисным аккаунтом с этой ролью, обычно используются с мобильных устройств вашего водителя доставки.
Пользователь-потребитель для доставки двигателей флота

roles/fleetengine.deliveryConsumer		 Предоставляет разрешение на поиск задач с использованием идентификатора отслеживания, а также на чтение, но не обновление информации о задачах. Токены, созданные учетной записью службы с этой ролью, обычно используются из веб-браузера потребителя доставки.
Доставка двигателей флота Суперпользователь

roles/fleetengine.deliverySuperUser		 Предоставляет разрешение всем API-интерфейсам средств доставки и задач. Токены, созданные учетной записью службы с этой ролью, обычно используются с ваших внутренних серверов.
Fleet Engine Delivery Fleet Reader

roles/fleetengine.deliveryFleetReader		 Предоставляет разрешение на чтение средств доставки и задач, а также на поиск задач с использованием идентификатора отслеживания. Токены, созданные сервисной учетной записью с этой ролью, обычно используются из веб-браузера оператора службы доставки.

Организации, которые предоставляют своим водителям-доставщикам устройства, управляемые корпоративными ИТ-специалистами, могут воспользоваться гибкостью, предлагаемой ролью доверенного водителя Fleet Engine, и выбрать интеграцию некоторых или всех взаимодействий Fleet Engine в мобильное приложение.

Организациям, поддерживающим политику «Привози свое собственное устройство», следует выбрать безопасную роль пользователя-недоверенного водителя Fleet Engine и полагаться только на мобильное приложение для отправки обновлений о местоположении транспортных средств в Fleet Engine. Все остальные взаимодействия должны происходить с внутренних серверов клиента.

SDK для драйверов и потребителей построены на основе этих стандартных ролей. Однако можно создавать собственные роли , которые позволяют объединять произвольный набор разрешений. Пакеты SDK для драйверов и потребителей будут отображать сообщения об ошибках, если необходимое разрешение отсутствует. В связи с этим мы настоятельно рекомендуем использовать представленный выше стандартный набор ролей вместо пользовательских ролей.

Создание сервисной учетной записи

Вы можете создать сервисную учетную запись, используя вкладку IAM & Admin > Service Accounts в Google Cloud Console. В раскрывающемся списке «Роль» выберите «Fleet Engine» и назначьте одну из ролей сервисному аккаунту. Рекомендуется указывать учетную запись, связанную с каждой ролью. Например, дайте учетной записи службы осмысленное имя.

Для удобства, если вам нужно создавать JWT для ненадежных клиентов, добавление пользователей в роль создателя токенов сервисной учетной записи позволяет им создавать токены с помощью инструментов командной строки gcloud .

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

Где my-user@example.com — это адрес электронной почты, используемый для аутентификации в gcloud ( gcloud auth list --format='value(account)' ).

Библиотека аутентификации Fleet Engine

Fleet Engine использует JWT для ограничения доступа к API Fleet Engine. Новая библиотека аутентификации Fleet Engine, доступная на Github , упрощает создание JWT Fleet Engine и надежно подписывает их.

Библиотека предоставляет следующие преимущества:

  • Упрощает процесс создания токенов Fleet Engine.
  • Предоставляет механизмы подписи токенов, отличные от использования файлов учетных данных (например, олицетворение учетной записи службы).
  • Прикрепляет подписанные токены к исходящим запросам, сделанным из заглушки gRPC или клиента GAPIC.

Создание веб-токена JSON (JWT) для авторизации

Если библиотека аутентификации Fleet Engine не используется, JWT необходимо создавать непосредственно в вашей кодовой базе. Это требует от вас глубокого понимания JWT и того, как они связаны с Fleet Engine. Вот почему мы НАСТОЯТЕЛЬНО рекомендуем воспользоваться библиотекой аутентификации Fleet Engine.

В Fleet Engine JWT обеспечивают кратковременную аутентификацию и гарантируют, что устройства могут изменять транспортные средства или выполнять только те задачи, для которых они авторизованы. JWT содержат заголовок и раздел утверждения. Раздел заголовка содержит такую ​​информацию, как используемый закрытый ключ (полученный из учетных записей служб) и алгоритм шифрования. Раздел утверждения содержит такую ​​информацию, как время создания токена, время жизни токена, службы, к которым токен претендует на доступ, а также другую информацию авторизации для ограничения доступа; например, идентификатор средства доставки.

Раздел заголовка JWT содержит следующие поля:

Поле Описание
Алг Алгоритм использования. `РС256`.
набрать Тип токена. `JWT`.
ребенок Идентификатор закрытого ключа вашего сервисного аккаунта. Вы можете найти это значение в поле `private_key_id` JSON-файла вашего сервисного аккаунта. Обязательно используйте ключ от учетной записи службы с правильным уровнем разрешений.

Раздел утверждений JWT содержит следующие поля:

Поле Описание
это Адрес электронной почты вашей учетной записи службы.
суб Адрес электронной почты вашей учетной записи службы.
аудит SERVICE_NAME вашего сервисного аккаунта, в данном случае https://fleetengine.googleapis.com/.
там Временная метка создания токена, указанная в секундах, прошедших с 00:00:00 UTC 1 января 1970 г. Допускается перекос в 10 минут. Если временная метка находится слишком далеко в прошлом или в будущем, сервер может сообщить об ошибке.
опыт Временная метка истечения срока действия токена, указанная в секундах, прошедших с 00:00:00 UTC 1 января 1970 года. Запрос завершается неудачей, если временная метка находится более чем на один час в будущем.
авторизация В зависимости от варианта использования может содержать «deliveryvehicleid», «trackingid», «taskid» или «taskids».

Создание токена JWT означает его подписание. Инструкции и примеры кода для создания и подписания JWT см. в разделе Авторизация учетной записи службы без OAuth . Затем вы можете прикрепить созданный токен к вызовам gRPC или другим методам, используемым для доступа к Fleet Engine.

Претензии JWT

Решение Last Mile Fleet Solution использует частные претензии. Использование частных утверждений гарантирует, что только авторизованные клиенты смогут получить доступ к своим данным. Например, когда ваша серверная часть выдает веб-токен JSON для мобильного устройства водителя доставки, этот токен должен содержать утверждение deliveryvehicleid со значением идентификатора средства доставки этого водителя. Затем, в зависимости от роли водителя, токены обеспечивают доступ только для конкретного идентификатора транспортного средства, а не для любого другого произвольного идентификатора транспортного средства.

Решение Last Mile Fleet Solution использует следующие частные претензии:

  • deliveryvehicleid — используйте при вызове API для каждого транспортного средства доставки.
  • taskid — используйте при вызове API для каждой задачи.
  • taskids — используйте при вызове BatchCreateTasksAPI . Это утверждение должно быть в форме массива, и массив должен содержать все идентификаторы задач, необходимые для выполнения запроса. Не включайте утверждения delivervehicleid , trackingid или taskid .
  • trackingid — используйте при вызове SearchTasksAPI . Заявление должно соответствовать идентификатору отслеживания в запросе. Не включайте утверждения delivervehicleid , taskid или taskids .

Токен также должен содержать соответствующее утверждение, когда вы вызываете API со своего внутреннего сервера, но вы можете использовать специальное значение звездочки («*») для утверждений deliveryvehicleid , taskid и trackingid . Звездочку («*») также можно использовать в утверждении taskids , но она должна быть единственным элементом в массиве.

Если вы хотите создать и подписать JSON непосредственно в качестве носителя токена, а не использовать токены доступа OAuth 2.0, прочтите инструкции по авторизации учетной записи службы без OAuth в документации Identity Developer.

Механизм прикрепления токена к вызову gRPC зависит от языка и платформы, используемых для выполнения вызова. Механизм указания токена для HTTP-вызова заключается во включении заголовка авторизации с токеном-носителем, значением которого является токен, как указано в примечаниях к авторизации для случаев отслеживания отдельных отправлений или производительности автопарка .

В следующем примере показан токен для операции над задачей с вашего внутреннего сервера:

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

В следующем примере показан токен для операции пакетного создания задач на внутреннем сервере:

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

В следующем примере показан токен для операции по доставке транспортного средства с вашего внутреннего сервера:

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

В следующем примере показан токен для конечных пользователей:

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

В следующем примере показан токен для вашего приложения-драйвера:

    {
      "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"
       }
    }
  • В поле kid в заголовке укажите идентификатор закрытого ключа вашей учетной записи службы. Это значение можно найти в поле private_key_id файла JSON вашего сервисного аккаунта.
  • В полях iss и sub укажите адрес электронной почты вашей учетной записи службы. Это значение можно найти в поле client_email JSON-файла вашего сервисного аккаунта.
  • В поле aud укажите https://SERVICE_NAME/ .
  • В поле iat укажите временную метку создания токена (в секундах), прошедшую с 00:00:00 UTC 1 января 1970 года. Допустимо отклонение в 10 минут. Если временная метка находится слишком далеко в прошлом или в будущем, сервер может сообщить об ошибке.
  • В поле exp укажите временную метку истечения срока действия токена (в секундах), начиная с 00:00:00 UTC 1 января 1970 года. Рекомендуемое значение — iat + 3600.

При подписании токена, который будет передан мобильному устройству или конечному пользователю, обязательно используйте файл учетных данных для роли драйвера доставки или потребителя. В противном случае мобильное устройство или конечный пользователь будут иметь возможность изменять или просматривать информацию, к которой у них не должно быть доступа.