Веб-токены JSON
Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
JSON Web Token (JWT) — это открытый веб-стандарт, используемый для аутентификации и авторизации обмена информацией между клиентом и сервером. Когда пользователь приложения впервые входит в систему с учётными данными соответствующей роли, сервер создаёт и возвращает закодированный JWT с цифровой подписью для использования в последующих запросах. Этот процесс одновременно аутентифицирует пользователя и предоставляет ему доступ к маршрутам, сервисам и ресурсам в зависимости от его роли учётной записи.
Fleet Engine требует использования JSON Web Tokens (JWT) для вызовов методов API из сред с низким уровнем доверия : смартфонов и браузеров.
JWT создается на вашем сервере, подписывается, шифруется и передается клиенту для последующих взаимодействий с сервером до тех пор, пока не истечет срок его действия или он не станет недействительным.
Ключевые детали
В отличие от ключей API, JWT имеют короткий срок действия и ограничивают выполнение только тех операций, которые разрешены для данной роли. Подробнее о JWT см. в разделе «JSON Web Tokens» в Википедии. Подробнее о ролях доступа см. в разделе «Роли учётных записей служб» в этом руководстве.
Элементы JWT
JWT содержат заголовок и раздел заявок. Раздел заявок содержит такую информацию, как закрытый ключ, полученный от учётных записей служб, и алгоритм шифрования. Раздел заявок содержит такую информацию, как время создания JWT, время его существования, сервисы, к которым JWT запрашивает доступ, и другую информацию об авторизации, определяющую область доступа, например, идентификатор транспортного средства доставки.
В следующей таблице приведены общие сведения о полях JWT, а также конкретная информация о том, где можно найти значения этих полей в вашем проекте Fleet Engine Cloud.
Поля заголовка JWT Поле | Описание |
|---|
алг | Алгоритм для использования. `RS256`. |
тип | Тип токена. `JWT`. |
ребенок | Идентификатор закрытого ключа вашей учётной записи службы. Это значение можно найти в поле private_key_id JSON-файла вашей учётной записи службы. Убедитесь, что вы используете ключ из учётной записи службы с соответствующим уровнем прав. |
Поля утверждений JWT Поле | Описание |
|---|
исс | Адрес электронной почты вашей учетной записи службы, указанный в поле client_email JSON-файла вашей учетной записи службы. |
суб | Адрес электронной почты вашей учетной записи службы, указанный в поле client_email JSON-файла вашей учетной записи службы. |
ауд | SERVICE_NAME вашего аккаунта службы, в данном случае https://fleetengine.googleapis.com/ |
iat | Временная метка создания JWT, указанная в секундах, прошедших с 00:00:00 UTC, January 1, 1970 . Допустимое отклонение составляет 10 минут. Если временная метка слишком далека от прошлого или будущего, сервер может сообщить об ошибке. |
опыт | Временная метка истечения срока действия JWT, указанная в секундах 00:00:00 UTC, January 1, 1970 . Запрос завершается ошибкой, если временная метка находится более чем на один час в будущем. |
разрешение | В зависимости от варианта использования может содержать deliveryvehicleid , trackingid , taskid или taskids . При указании идентификаторов задач область авторизации должна быть массивом в одной из следующих форм: "taskids": ["task_id_one","task_id_two"] или "taskids": ["*"] |
Требования Fleet Engine JWT
Fleet Engine использует приватные заявки. Использование приватных заявок гарантирует, что доступ к своим данным получат только авторизованные клиенты.
Например, когда ваш сервер выдаёт JSON-веб-токен для мобильного устройства водителя, он должен содержать либо утверждение vehicleid , либо утверждение deliveryvehicleid со значением идентификатора транспортного средства этого водителя. Тогда, в зависимости от роли водителя, JWT разрешают доступ только к конкретному идентификатору транспортного средства, а не к любому другому произвольному идентификатору транспортного средства.
Fleet Engine использует следующие частные утверждения:
Поездки по запросу
-
vehicleid :- Driver SDK всегда использует это утверждение, независимо от того, действует ли оно для поездки или транспортного средства. Бэкэнд Fleet Engine гарантирует, что транспортное средство связано с запрошенной поездкой, прежде чем вносить изменения.
- JWT может охватывать как транспортные, так и рейсовые операции, даже если это не требуется, что может упростить реализацию подписания JWT.
-
tripid :- Consumer SDK всегда использует это утверждение.
- JWT может охватывать как транспортные, так и поездочные операции, даже если это не требуется, что может упростить реализацию подписи токена.
Запланированные задачи
deliveryvehicleid
Используется при вызове API для каждого транспортного средства доставки.
taskid
Используется при вызове API для каждой задачи.
taskids
Используется при вызове BatchCreateTasksAPI . Это утверждение должно быть представлено в виде массива, содержащего все идентификаторы задач, необходимые для выполнения запроса. Не включайте утверждения delivervehicleid , trackingid или taskid .
trackingid
Используется при вызове GetTaskTrackingInfoAPI . Утверждение должно соответствовать идентификатору отслеживания в запросе. Не включайте утверждения delivervehicleid , taskid или taskids .
Что дальше?
Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons "С указанием авторства 4.0", а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.
Последнее обновление: 2025-09-04 UTC.
[[["Прост для понимания","easyToUnderstand","thumb-up"],["Помог мне решить мою проблему","solvedMyProblem","thumb-up"],["Другое","otherUp","thumb-up"]],[["Отсутствует нужная мне информация","missingTheInformationINeed","thumb-down"],["Слишком сложен/слишком много шагов","tooComplicatedTooManySteps","thumb-down"],["Устарел","outOfDate","thumb-down"],["Проблема с переводом текста","translationIssue","thumb-down"],["Проблемы образцов/кода","samplesCodeIssue","thumb-down"],["Другое","otherDown","thumb-down"]],["Последнее обновление: 2025-09-04 UTC."],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]
