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

В этом документе описывается, как выпускать 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 » раздела «Безопасность в Fleet Engine» . Роли учётных записей служб , используемые Fleet Engine, см. в разделе «Роли учётных записей служб». В следующем разделе представлен список примеров JWT для рейсов по требованию и запланированных задач.

Общие рекомендации

  • Используйте соответствующие учетные записи служб и роли . Учетная запись служб и связанная с ней роль гарантируют, что пользователь, запрашивающий токен, имеет право просматривать информацию, к которой токен предоставляет ему доступ. В частности:
    • При подписании JWT для передачи на мобильное устройство используйте учетную запись службы для роли Driver или 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 для отслеживания автопарка» .

  • Подпишите токен, используя роль IAM Fleet Engine Delivery Fleet Reader Cloud.

   {
      "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": "*"
       }
    }

Что дальше?