Tokens web JSON
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
Un token web JSON (JWT) es un estándar web abierto que se usa para autenticar y autorizar intercambios de información entre un cliente y un servidor. Cuando un usuario de la app accede por primera vez con las credenciales de rol adecuadas, el servidor crea y devuelve un JWT codificado y firmado digitalmente para usarlo en solicitudes posteriores.
Este proceso autentica al usuario y lo autoriza a acceder a rutas, servicios y recursos según el rol de su cuenta.
Fleet Engine requiere el uso de tokens web JSON (JWT) para las llamadas a métodos de la API desde entornos de baja confianza: smartphones y navegadores.
Un JWT se origina en tu servidor, se firma, se encripta y se pasa al cliente para las interacciones posteriores del servidor hasta que vence o ya no es válido.
Detalles clave
A diferencia de las claves de API, los JWT tienen una vida útil corta y limitan las operaciones solo a aquellas que el rol está autorizado a realizar. Para obtener más información sobre los JWT, consulta Tokens web JSON en Wikipedia. Para obtener detalles sobre los roles de acceso, consulta Roles de cuentas de servicio en esta guía.
Elementos de JWT
Los JWTs contienen un encabezado y una sección de reclamos. La sección del encabezado contiene información como la clave privada obtenida de las cuentas de servicio y el algoritmo de encriptación. La sección de la declaración contiene información como la hora de creación y el tiempo de vida del JWT, los servicios a los que el JWT declara tener acceso y otra información de autorización para definir el alcance del acceso; por ejemplo, el ID del vehículo de reparto.
En la siguiente tabla, se proporcionan detalles descriptivos sobre los campos de JWT en general, así como información específica sobre dónde puedes encontrar los valores de estos campos en tu proyecto de Fleet Engine Cloud.
Campos del encabezado JWT
Campo |
Descripción |
alg |
Es el algoritmo que se usará. `RS256`. |
typ |
Es el tipo de token. `JWT`. |
niño |
Es el ID de la clave privada de tu cuenta de servicio. Puedes encontrar este valor en el campo private_key_id de tu archivo JSON de la cuenta de servicio. Asegúrate de usar una clave de una cuenta de servicio con el nivel correcto de permisos. |
Campos de reclamaciones de JWT
Campo |
Descripción |
iss |
La dirección de correo electrónico de tu cuenta de servicio, que se encuentra en el campo client_email de tu archivo JSON de cuenta de servicio |
sub |
La dirección de correo electrónico de tu cuenta de servicio, que se encuentra en el campo client_email de tu archivo JSON de cuenta de servicio |
aud |
El SERVICE_NAME de tu cuenta de servicio, en este caso, https://fleetengine.googleapis.com/ |
iat |
Es la marca de tiempo en la que se creó el JWT, especificada en segundos transcurridos desde las 00:00:00 UTC, January 1, 1970. con una tolerancia de 10 minutos debida al sesgo
Si la marca de tiempo es demasiado antigua o futura, es posible que el servidor informe un error. |
exp |
Es la marca de tiempo en la que vence el JWT, especificada en segundos transcurridos desde 00:00:00 UTC, January 1, 1970. La solicitud falla si la marca de tiempo es más de una hora en el futuro. |
autorización |
Según el caso de uso, puede contener deliveryvehicleid, trackingid, taskid o taskids.
Si se especifican taskids, el alcance de autorización debe ser un array en uno de los siguientes formatos:
"taskids": ["task_id_one","task_id_two"]
o
"taskids": ["*"] |
Reclamaciones de JWT de Fleet Engine
Fleet Engine usa reclamos privados. El uso de reclamos privados garantiza que solo los clientes autorizados puedan acceder a sus propios datos.
Por ejemplo, cuando tu servidor emite un token web JSON para el dispositivo móvil de un conductor, debe contener el reclamo vehicleid o el reclamo deliveryvehicleid con el valor del ID del vehículo de ese conductor. Luego, según el rol del conductor, los JWTs habilitan el acceso solo para el ID de vehículo específico y no para ningún otro ID de vehículo arbitrario.
Fleet Engine usa los siguientes reclamos privados:
Viajes a pedido
-
vehicleid:
- El SDK de Driver siempre usa este reclamo, ya sea que opere en un viaje o en un vehículo. El backend de Fleet Engine garantiza que el vehículo esté asociado con el viaje solicitado antes de realizar la modificación.
-
El JWT puede abarcar operaciones tanto del vehículo como del viaje, incluso si no son necesarias, lo que puede simplificar la implementación de la firma del JWT.
-
tripid:
- El SDK de Consumer siempre usa este reclamo.
-
El JWT puede abarcar las operaciones del vehículo y del viaje, incluso si no es necesario, lo que puede simplificar la implementación de la firma del token.
Tareas programadas
-
deliveryvehicleid
Se usa cuando se llama a las APIs por vehículo de entrega.
-
taskid
Se usa cuando se llama a las APIs por tarea.
-
taskids
Se usa cuando se llama a BatchCreateTasksAPI. Este reclamo debe estar en formato de array, y el array debe contener todos los IDs de tareas necesarios para completar la solicitud. No incluyas afirmaciones sobre delivervehicleid, trackingid ni taskid.
-
trackingid
Se usa cuando se llama a GetTaskTrackingInfoAPI. El reclamo debe coincidir con el ID de seguimiento de la solicitud. No incluyas afirmaciones sobre delivervehicleid, taskid ni taskids.
¿Qué sigue?
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2025-08-31 (UTC)
[null,null,["Última actualización: 2025-08-31 (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."]]
