В этом разделе объясняются концепции аутентификации и авторизации применительно к реализации 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 определяют объем разрешенных действий для вызывающей стороны. Например, роли суперпользователя разрешено делать все, а роли ненадежного водителя разрешено выполнять только минимальные обновления местоположения.
Роли IAM связаны с учетными записями служб.
Заявления JWT дополнительно ограничивают объекты, с которыми может работать вызывающий объект. Это могут быть конкретные задачи или средства доставки.
Запросы, отправляемые в Fleet Engine, всегда содержат JWT.
- Поскольку JWT связаны с учетными записями службы, запросы, отправляемые в Fleet Engine, неявно связаны с учетной записью службы, связанной с JWT.
Чтобы запросить соответствующий JWT, который вы затем можете передать в Fleet Engine, ваш код, работающий в среде с низким уровнем доверия, должен сначала вызвать ваш код, работающий в среде с полным доверием.
Fleet Engine выполняет следующие проверки безопасности:
Роли IAM, связанные с учетной записью службы, обеспечивают правильную авторизацию для вызывающей стороны для выполнения вызова API.
Утверждения JWT, переданные в запросе, обеспечивают правильную авторизацию вызывающего объекта для работы с сущностью.
Поток аутентификации
На следующей диаграмме последовательности показаны эти детали процесса проверки подлинности.
Администратор автопарка создает сервисные учетные записи.
Администратор парка назначает определенные роли IAM сервисным учетным записям.
Администратор автопарка настраивает серверную часть с учетными записями службы.
Клиентское приложение запрашивает JWT из серверной части партнера. Запрашивающим может быть приложение Driver, приложение Consumer или приложение мониторинга.
Fleet Engine выдает JWT для соответствующей учетной записи службы. Клиентское приложение получает JWT.
Клиентское приложение использует JWT для подключения к Fleet Engine для чтения или изменения данных в зависимости от ролей IAM, назначенных ему на этапе настройки.
Настройка облачного проекта
Чтобы настроить облачный проект, сначала создайте проект, а затем создайте учетные записи служб.
Чтобы создать проект Google Cloud:
- Создайте проект Google Cloud с помощью Google Cloud Console.
- Используя панель API и сервисов, включите Local Rides and Delivery API.
Сервисные аккаунты и роли IAM
Учетная запись службы — это особый тип учетной записи, который используется приложением, а не человеком. Как правило, учетная запись службы используется для создания JWT, которые предоставляют разные наборы разрешений в зависимости от роли. Чтобы уменьшить вероятность злоупотреблений, вы можете создать несколько учетных записей служб, каждая из которых имеет минимальный набор необходимых ролей.
Last Mile Fleet Solution использует следующие роли:
Роль | Описание |
---|---|
Доверенный водитель Fleet Engine Deliveryroles/fleetengine.deliveryTrustedDriver | Предоставляет разрешение на создание и обновление транспортных средств и задач доставки, включая обновление местоположения транспортного средства и статуса или результата задачи. Токены, отчеканенные учетной записью службы с этой ролью, обычно используются с мобильных устройств вашего водителя доставки или с ваших внутренних серверов. |
Ненадежный водитель, поставляющий двигатель флотаroles/fleetengine.deliveryUntrustedDriver | Предоставляет разрешение на обновление местоположения транспортного средства доставки. Токены, отчеканенные учетной записью службы с этой ролью, обычно используются с мобильных устройств вашего водителя доставки. |
Потребитель-потребитель доставки двигателя паркаroles/fleetengine.deliveryConsumer | Предоставляет разрешение на поиск задач с использованием идентификатора отслеживания и чтение, но не обновление информации о задаче. Токены, отчеканенные учетной записью службы с этой ролью, обычно используются в веб-браузере получателя доставки. |
Суперпользователь по доставке двигателей флотаroles/fleetengine.deliverySuperUser | Предоставляет разрешение на все средства доставки и API-интерфейсы задач. Токены, отчеканенные учетной записью службы с этой ролью, обычно используются с ваших внутренних серверов. |
Считыватель флота для доставки двигателейroles/fleetengine.deliveryFleetReader | Предоставляет разрешение на чтение средств доставки и задач, а также на поиск задач с использованием идентификатора отслеживания. Токены, отчеканенные сервисной учетной записью с этой ролью, обычно используются в веб-браузере оператора службы доставки. |
Организации, предоставляющие своим водителям устройства, управляемые корпоративными ИТ-отделами, могут воспользоваться преимуществами гибкости, предлагаемой ролью доверенного водителя Fleet Engine, и выбрать интеграцию некоторых или всех взаимодействий Fleet Engine в мобильное приложение.
Организации, поддерживающие политику «Принеси свое собственное устройство», должны выбрать безопасность роли ненадежного водителя Fleet Engine и полагаться только на мобильное приложение для отправки обновлений местоположения транспортного средства в Fleet Engine. Все остальные взаимодействия должны исходить от внутренних серверов клиента.
Driver и Consumer SDK построены вокруг этих стандартных ролей. Однако можно создавать настраиваемые роли , которые позволяют объединять произвольный набор разрешений. Пакеты Driver и Consumer 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 использует JWT для ограничения доступа к API Fleet Engine. Новая библиотека аутентификации Fleet Engine, доступная на Github , упрощает создание JWT Fleet Engine и надежно подписывает их.
Библиотека предоставляет следующие преимущества:
- Упрощает процесс создания токенов Fleet Engine.
- Предоставляет механизмы подписи маркеров, отличные от использования файлов учетных данных (например, олицетворение учетной записи службы).
- Прикрепляет подписанные токены к исходящим запросам, сделанным либо из заглушки gRPC, либо из клиента GAPIC.
Создание JSON Web Token (JWT) для авторизации
Если библиотека аутентификации Fleet Engine не используется, JWT необходимо создавать непосредственно в вашей кодовой базе. Это требует от вас глубокого понимания JWT и того, как они связаны с Fleet Engine. Вот почему мы НАСТОЯТЕЛЬНО рекомендуем воспользоваться библиотекой аутентификации Fleet Engine.
В Fleet Engine JWT обеспечивают кратковременную аутентификацию и гарантируют, что устройства могут изменять только транспортные средства или задачи, для которых они авторизованы. JWT содержат заголовок и раздел утверждений. Раздел заголовка содержит такую информацию, как закрытый ключ для использования (полученный из учетных записей службы) и алгоритм шифрования. Раздел утверждения содержит такую информацию, как время создания токена, время жизни токена, службы, к которым токен требует доступа, и другую информацию об авторизации для доступа вниз; например, идентификатор транспортного средства доставки.Раздел заголовка JWT содержит следующие поля:
Поле | Описание |
---|---|
Алг | Алгоритм использования. `РС256`. |
тип | Тип токена. `ДВТ`. |
ребенок | Идентификатор закрытого ключа вашей служебной учетной записи. Вы можете найти это значение в поле `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, прочитайте инструкции по авторизации учетной записи службы {.external} без 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://ИМЯ_СЛУЖБЫ/ . - В поле
iat
укажите отметку времени создания токена в секундах, прошедших с 00:00:00 UTC 1 января 1970 года. Разрешить 10 минут для перекоса. Если отметка времени находится слишком далеко в прошлом или в будущем, сервер может сообщить об ошибке. - Для поля
exp
укажите отметку времени, когда истечет срок действия маркера, в секундах с 00:00:00 UTC, 1 января 1970 года. Рекомендуемое значение —iat
+ 3600.
При подписании токена, который будет передан мобильному устройству или конечному пользователю, обязательно используйте файл учетных данных для роли «Водитель доставки» или «Потребитель». В противном случае мобильное устройство или конечный пользователь смогут изменять или просматривать информацию, к которой у них не должно быть доступа.