В этом разделе объясняются концепции аутентификации и авторизации при интеграции с Fleet Engine.
Вы можете настроить возможности, предоставляемые Last Mile Fleet Solution, через Google Cloud Console . SDK Fleet Engine требуют использования веб-токенов JSON (JWT), подписанных соответствующей учетной записью службы .
Обзор
Серверные части клиента, выполняющие аутентификацию и авторизацию в Fleet Engine, должны использовать стандартные механизмы учетных данных приложения по умолчанию .
Fleet Engine также принимает вызовы, исходящие из сред с низким уровнем доверия, таких как смартфоны и браузеры. Чтобы защитить секретные ключи учетной записи службы, подходящие только для доверенных сред, серверные части клиентов должны генерировать подписанные веб-токены JSON (JWT) с дополнительными утверждениями, специфичными для Fleet Engine, которые затем могут быть выданы в недоверенные среды, такие как мобильные телефоны.
Принципы разработки аутентификации
Процесс аутентификации Fleet Engine включает в себя следующие принципы проектирования.
Роли IAM определяют набор разрешений на ресурсы, разрешенные участнику. Например, ролям администратора разрешено делать все с учетными данными приложения по умолчанию, тогда как роли ненадежного водителя* разрешено только обновлять местоположение транспортного средства и ограничено использованием JWT для аутентификации и авторизации.
Для ненадежных сред утверждения JWT дополнительно ограничивают объекты, с которыми может работать вызывающая сторона. Это могут быть конкретные задачи или средства доставки.
Ваш код, работающий в среде с низким уровнем доверия, должен сначала вызвать ваш код, работающий в доверенной среде, для выдачи JWT.
Fleet Engine выполняет следующие проверки безопасности вызовов API для ресурса:
Вызывающий субъект имеет соответствующие разрешения (через назначение роли) для действий с ресурсом.
Для ролей, не являющихся администраторами, утверждения JWT, передаваемые в запросе, предоставляют необходимые разрешения для ресурса.
Поток аутентификации
Следующая диаграмма последовательности демонстрирует детали процесса аутентификации.
Администратор автопарка создает сервисные учетные записи.
Администратор автопарка назначает определенные роли IAM сервисным учетным записям.
Администратор автопарка настраивает свою серверную часть с помощью учетных записей служб и учетных данных приложения по умолчанию.
Клиентское приложение запрашивает JWT у серверной части клиента. Запрашивающим может быть приложение «Драйвер», приложение «Потребитель» или приложение для мониторинга.
Серверная часть клиента подписывает и выдает JWT для соответствующей учетной записи службы. Клиентское приложение получает JWT.
Клиентское приложение использует JWT для подключения к Fleet Engine для чтения или изменения данных в зависимости от ролей IAM, назначенных ему на этапе установки.
Настройка облачного проекта
Чтобы настроить облачный проект, сначала создайте проект, а затем создайте учетные записи служб.
Чтобы создать проект Google Cloud:
- Создайте проект Google Cloud с помощью Google Cloud Console.
- Используя панель API и служб, включите API местных поездок и доставок.
Учетные записи служб и роли IAM
Служебная учетная запись — это особый вид учетной записи, которая используется приложением, а не человеком. Обычно учетная запись службы используется для создания JWT, которые предоставляют разные наборы разрешений в зависимости от роли. Чтобы уменьшить вероятность злоупотреблений, вы можете создать несколько учетных записей служб, каждая из которых имеет минимальный набор необходимых ролей ().
Last Mile Fleet Solution использует следующие роли:
Роль | Описание |
---|---|
Доверенный водитель Fleet Engine Deliveryroles/fleetengine.deliveryTrustedDriver | Предоставляет разрешение на создание и обновление средств доставки и задач, включая обновление местоположения средства доставки, а также статуса или результата задачи. Токены, созданные сервисным аккаунтом с этой ролью, обычно используются с мобильных устройств вашего водителя доставки или с ваших внутренних серверов. |
Недоверенный водитель-пользователь Fleet Engine Deliveryroles/fleetengine.deliveryUntrustedDriver | Предоставляет разрешение на обновление местоположения средства доставки. Токены, созданные сервисным аккаунтом с этой ролью, обычно используются с мобильных устройств вашего водителя доставки. |
Пользователь-потребитель для доставки двигателей флотаroles/fleetengine.deliveryConsumer | Предоставляет разрешение на поиск задач с использованием идентификатора отслеживания, а также на чтение, но не обновление информации о задачах. Токены, созданные учетной записью службы с этой ролью, обычно используются из веб-браузера потребителя доставки. |
Администратор по доставке двигателей флотаroles/fleetengine.deliveryAdmin | Предоставляет разрешение на чтение и запись для ресурсов доставки. Участникам с этой ролью не нужно использовать JWT, вместо этого им следует использовать учетные данные приложения по умолчанию. Пользовательские утверждения JWT игнорируются. Эта роль должна быть ограничена доверенными средами (серверная часть клиента). |
roles/fleetengine.deliverySuperUser | Предоставляет разрешение всем API-интерфейсам средств доставки и задач. Токены, созданные учетной записью службы с этой ролью, обычно используются с ваших внутренних серверов. |
Fleet Engine Delivery Fleet Readerroles/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.
- Предоставляет механизмы подписи токенов, отличные от использования файлов учетных данных (например, олицетворение учетной записи службы).
Создание JSON Web Token (JWT) для авторизации
Если библиотека аутентификации Fleet Engine не используется, JWT необходимо создавать непосредственно в вашей кодовой базе. Это требует от вас глубокого понимания JWT и того, как они связаны с Fleet Engine. Вот почему мы НАСТОЯТЕЛЬНО рекомендуем воспользоваться библиотекой аутентификации Fleet Engine.
В Fleet Engine JWT обеспечивают кратковременную аутентификацию и гарантируют, что устройства могут изменять транспортные средства или выполнять только те задачи, для которых они авторизованы. JWT содержат заголовок и раздел утверждения. Раздел заголовка содержит такую информацию, как используемый закрытый ключ (полученный из учетных записей служб) и алгоритм шифрования. Раздел утверждения содержит такую информацию, как время создания токена, время жизни токена, службы, к которым токен претендует на доступ, а также другую информацию авторизации для ограничения доступа; например, идентификатор средства доставки.Раздел заголовка JWT содержит следующие поля:
Поле | Описание |
---|---|
alg | Алгоритм использования. `РС256`. |
typ | Тип токена. `JWT`. |
kid | Идентификатор закрытого ключа вашего сервисного аккаунта. Вы можете найти это значение в поле `private_key_id` JSON-файла вашего сервисного аккаунта. Обязательно используйте ключ от учетной записи службы с правильным уровнем разрешений. |
Раздел утверждений JWT содержит следующие поля:
Поле | Описание |
---|---|
iss | Адрес электронной почты вашей учетной записи службы. |
sub | Адрес электронной почты вашей учетной записи службы. |
aud | SERVICE_NAME вашего сервисного аккаунта, в данном случае https://fleetengine.googleapis.com/. |
iat | Временная метка создания токена, указанная в секундах, прошедших с 00:00:00 UTC 1 января 1970 г. Допускается рассогласование в 10 минут. Если временная метка находится слишком далеко в прошлом или в будущем, сервер может сообщить об ошибке. |
exp | Временная метка истечения срока действия токена, указанная в секундах, прошедших с 00:00:00 UTC 1 января 1970 года. Запрос завершается неудачей, если временная метка находится более чем на один час в будущем. |
authorization | В зависимости от варианта использования может содержать «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
— используйте при вызовеGetTaskTrackingInfoAPI
. Заявление должно соответствовать идентификатору отслеживания в запросе. Не включайте утверждения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.
При подписании токена, который будет передан мобильному устройству или конечному пользователю, обязательно используйте файл учетных данных для роли драйвера доставки или потребителя. В противном случае мобильное устройство или конечный пользователь будут иметь возможность изменять или просматривать информацию, к которой у них не должно быть доступа.