В этом документе рассказывается, как выпускать веб-токены JSON, чтобы разрешить веб- и мобильным приложениям доступ к данным Fleet Engine. Если вы ещё этого не сделали, прочитайте статью Веб-токены JSON в разделе Безопасность в Fleet Engine. С помощью сервиса Fleet Engine вы можете выпускать JWT одним из следующих способов:
- Использовать библиотеку авторизации. Мы рекомендуем этот подход, если ваша база кода написана на Java. Эта библиотека позволяет выпускать JWT для всех сценариев использования сервиса и значительно упрощает реализацию.
- Создайте собственные токены JWT. Если вы не можете использовать нашу библиотеку JWT, вам нужно будет создать токены в собственной базе кода. В этом разделе приведены примеры JWT для каждого сценария.
Как работают JWT
Для ненадежных сред, таких как мобильные телефоны и веб-браузеры, ваш бэкенд-сервер выдает JWT, которые работают следующим образом:
Клиентский код, выполняемый в среде с низким уровнем доверия, вызывает серверный код, выполняемый в среде с полным доверием, чтобы запросить соответствующий JWT для передачи в Fleet Engine.
Токены JWT связаны с сервисными аккаунтами, поэтому запросы, отправляемые в Fleet Engine, неявно связаны с сервисным аккаунтом, который подписал токен JWT.
Утверждения JWT дополнительно ограничивают ресурсы, с которыми может работать клиент, например определенные транспортные средства, поездки или задачи.
Используйте библиотеку авторизации для Java
Чтобы использовать библиотеку авторизации Fleet Engine для Java, перейдите в репозиторий GitHub. Библиотека упрощает создание токенов JWT Fleet Engine и их безопасное подписание. Он предоставляет следующие возможности:
- Объявления зависимостей проекта
- Полный список всех ролей сервисных аккаунтов для поездок по запросу или запланированных задач.
- Механизмы подписи токенов, отличные от использования файлов учетных данных, например выдача себя за сервисный аккаунт.
- Прикрепляет подписанные токены к исходящим запросам, отправленным из заглушки gRPC или клиентской библиотеки Google API Codegen (GAPIC).
- Инструкции по интеграции подписывающих сторон с клиентскими библиотеками Fleet Engine
Если вы выпускаете JWT из своего кода
Если вы не можете использовать библиотеку авторизации для Java, вам нужно реализовать JWT в собственной базе кода. В этом разделе приведены рекомендации по созданию собственных токенов. Список полей и утверждений JWT приведен в разделе Веб-токены JSON статьи Безопасность в Fleet Engine. Роли сервисных аккаунтов, используемые Fleet Engine, перечислены в разделе Роли сервисных аккаунтов. Примеры токенов JWT для поездок по запросу и запланированных задач приведены в следующем разделе.
Общие рекомендации
- Используйте подходящие сервисные аккаунты и роли. Сервисный аккаунт и связанная с ним роль гарантируют, что пользователь, запрашивающий токен, имеет право на просмотр информации, к которой токен предоставляет доступ. В частности:
- Если вы подписываете JWT, который будет передан на мобильное устройство, используйте сервисный аккаунт для роли Driver SDK или Consumer SDK. В противном случае мобильное устройство может изменять данные и получать доступ к ним, даже если у него нет на это прав.
- Если вы подписываете JWT для привилегированных вызовов, используйте сервисный аккаунт с ролью администратора Fleet Engine при использовании ADC или JWT. В противном случае операция не будет выполнена.
- Предоставляйте доступ только к созданным токенам. Никогда не сообщайте никому учетные данные, используемые для создания токенов.
- Для вызовов gRPC механизм прикрепления токена зависит от языка и фреймворка, используемых для вызова. Чтобы указать токен для HTTP-вызова, включите заголовок
Authorizationс токеном на предъявителя, значением которого является токен. - Возвращает срок действия. Сервер должен возвращать срок действия токена, обычно в секундах.
- Если вам нужно создать и подписать JSON непосредственно в качестве носителя токена, а не использовать токены доступа OAuth 2.0, ознакомьтесь с инструкциями по авторизации сервисного аккаунта без OAuth в документации для разработчиков по идентификации.
Для поездок по запросу
- При создании полезной нагрузки JWT добавьте дополнительное утверждение в раздел авторизации с ключом
vehicleidилиtripid, заданным в качестве значения идентификатора транспортного средства или идентификатора поездки, для которого выполняется вызов.
Для запланированных задач
- Когда ваш сервер вызывает другие API, токены также должны содержать соответствующее утверждение. Для этого можно сделать следующее:
- Установите для каждого ключа значение
*. - Предоставьте пользователю доступ ко всем
taskidsиdeliveryvehicleids. Для этого добавьте в раздел авторизации дополнительное утверждение с ключамиtaskidиdeliveryvehicleid. - Если в утверждении
taskidsиспользуется звездочка (*), она должна быть единственным элементом в массиве.
- Установите для каждого ключа значение
Примеры JWT для поездок по запросу
В этом разделе приведены примеры JWT для распространенных сценариев, если вы используете поездки по запросу.
Пример токена для операции в приложении для водителей
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"vehicleid": "driver_12345"
}
}
Пример токена для операции в приложении для пользователей
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_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": {
"tripid": "trip_54321"
}
}
Примеры JWT для запланированных задач
В этом разделе приведены примеры JWT для типичных сценариев, если вы используете запланированные задачи.
Пример токена для приложения водителя
{
"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"
}
}
Пример токена для приложения для пользователей
{
"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"
}
}
Примеры JWT для операций с автопарком
В этом разделе приведен пример JWT для типичного сценария работы автопарка.
Пример токена для отслеживания всех задач и транспортных средств в автопарке
В примере ниже показан токен, который отслеживает все задачи и транспортные средства в автопарке из веб-приложения, используемого оператором. Для этих операций требуются более широкие разрешения, чем для клиентских приложений. Инструкции по настройке клиентской библиотеки JavaScript для отслеживания транспорта, в которой будет использоваться этот токен, приведены в статье Как настроить библиотеку JavaScript для отслеживания транспорта.
Подпишите токен с помощью роли
Fleet Engine Delivery Fleet ReaderCloud IAM.
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
"sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"scope": "https://www.googleapis.com/auth/xapi",
"authorization": {
"taskid": "*",
"deliveryvehicleid": "*",
}
}
Альтернативный способ аутентификации для операций на бэкенд-сервере
Мы рекомендуем использовать ADC для аутентификации операций на бэкенд-сервере. Если вы не можете использовать ADC и вам нужно использовать JWT, ознакомьтесь с этими примерами.
Пример токена для операции на бэкенд-сервере по запросу
{ "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": { "vehicleid": "*", "tripid": "*" } }
Пример токена для запланированной операции на бэкенд-сервере
{ "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": "*" } }
Дальнейшие действия
- Проверьте настройки, чтобы создать пробное транспортное средство и убедиться, что токены работают правильно.
- Информацию о том, как использовать ADC вместо JWT для операций на бэкенд-сервере, можно найти в обзоре безопасности.