В этом документе рассказывается, как выпускать веб-токены JSON, чтобы предоставить доступ к данным Fleet Engine веб- и мобильным приложениям. Если вы ещё этого не сделали, прочитайте раздел Веб-токены JSON в статье Безопасность в Fleet Engine. С помощью сервиса Fleet Engine вы можете выпускать JWT одним из следующих способов:
- Используйте библиотеку авторизации. Google рекомендует этот подход, если ваша база кода написана на 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 для использования в привилегированных вызовах, при использовании ADC или JWT используйте сервисный аккаунт с правильной ролью администратора Fleet Engine. В противном случае операция завершится неудачно.
- Делитесь только созданными токенами. Никогда не сообщайте никому учетные данные, используемые для создания токенов.
- Для вызовов 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 для отслеживания транспорта.
Подпишите токен, используя роль
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": "*",
}
}
Альтернативный способ аутентификации для операций на бэкенд-сервере
Google рекомендует использовать 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 для операций на бэкенд-сервере, можно найти в обзоре безопасности.