Эта страница переведена с помощью Cloud Translation API.

Выпуск веб-токенов JSON

В этом документе описывается, как выдавать веб-токены 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 или Consumer SDK. В противном случае мобильное устройство может изменить данные и получить доступ к данным, к которым у него не должно быть доступа.
- При подписании JWT, который будет использоваться для привилегированных вызовов , используйте учетную запись службы с правильной ролью администратора Fleet Engine при использовании ADC или JWT. В противном случае операция не удастся.
Делитесь только созданными токенами . Никогда не передавайте учетные данные, использованные для создания токенов.
Для вызовов gRPC механизм прикрепления токена зависит от языка и платформы, используемых для выполнения вызова. Механизм указания токена для HTTP-вызова заключается во включении заголовка Authorization с токеном-носителем, значением которого является токен.
Возвратите время истечения срока действия. Ваш сервер должен вернуть срок действия токена, обычно в секундах.
Если вам необходимо создать и подписать JSON непосредственно в качестве носителя токена , а не использовать токены доступа OAuth 2.0, прочтите инструкции по авторизации учетной записи службы без OAuth в документации Identity Developer.

Для поездок по требованию

При создании полезных данных 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 Reader .
Примечание. Токен, созданный с использованием этой роли, предоставляет некоторые разрешения объектам Fleet Engine. Убедитесь, что ваш бэкэнд передает токен только аутентифицированным пользователям.

   {
      "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 для операций внутреннего сервера см. в разделе Обзор безопасности .