В этом документе описывается, как выдавать JSON Web Tokens в рамках предоставления вашим веб- и мобильным приложениям доступа к данным Fleet Engine. Если вы еще этого не сделали, прочтите JSON Web Tokens в разделе Безопасность в 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 Web Tokens в разделе Security in Fleet Engine. Список ролей учетных записей служб, используемых Fleet Engine, см. в разделе Service account roles. В следующем разделе приведен список примеров JWT для поездок по требованию или запланированных задач.
Общие рекомендации
- Используйте соответствующие учетные записи служб и роли . Учетная запись службы и связанная с ней роль гарантируют, что пользователь, запрашивающий токен, имеет право просматривать информацию, к которой токен предоставляет ему доступ. В частности:
- При подписании JWT для передачи на мобильное устройство используйте учетную запись службы для роли Driver или Consumer SDK. В противном случае мобильное устройство может изменять и получать доступ к данным, к которым у него не должно быть доступа.
- Если подписываете JWT для использования в привилегированных вызовах , используйте учетную запись службы с правильной ролью Fleet Engine Admin при использовании 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 для реализации на стороне клиента, которая будет использовать этот токен:
Подпишите токен, используя роль IAM
Fleet Engine Delivery Fleet ReaderCloud.
{
"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 для операций внутреннего сервера см. в разделе Обзор безопасности .