En este documento, se explica cómo emitir tokens web JSON como parte de la habilitación del acceso de tus apps web y para dispositivos móviles a los datos de Fleet Engine. Si aún no lo hiciste, lee Tokens web JSON en la sección Seguridad en Fleet Engine. Con el servicio de Fleet Engine, puedes emitir JWT de una de las siguientes maneras:
- Usa la biblioteca de autorización: Google recomienda usar este enfoque cuando tu base de código está escrita en Java. Esta biblioteca controla la emisión de JWT para todas las situaciones de casos de uso que puedas necesitar con el servicio y simplifica en gran medida tu implementación.
- Crea tus propios JWT: Si no puedes usar nuestra biblioteca de JWT, deberás compilarlos en tu propia base de código. En esta sección, se proporcionan los distintos ejemplos de JWT para cada situación.
Cómo funcionan los JWT
Para entornos no confiables, como teléfonos celulares y navegadores web, el servidor de backend emite JWT que funcionan de la siguiente manera:
Tu código cliente que se ejecuta en un entorno de confianza baja llama a tu código de servidor que se ejecuta en un entorno de confianza total para solicitar el JWT adecuado que se pasará a Fleet Engine.
Los JWT están asociados con cuentas de servicio, por lo que las solicitudes que se envían a Fleet Engine están asociadas de forma implícita con la cuenta de servicio que firmó el JWT.
Los reclamos de JWT restringen aún más los recursos en los que el cliente puede operar, como vehículos, viajes o tareas específicos.
Cómo usar la biblioteca de autorización para Java
Para usar la biblioteca de autorización de Fleet Engine para Java, visita el repositorio de GitHub. La biblioteca simplifica la construcción de JWT de Fleet Engine y los firma de forma segura. Proporciona lo siguiente:
- Declaraciones de dependencias del proyecto
- Una lista completa de todos los roles de cuentas de servicio para viajes a pedido o tareas programadas
- Mecanismos de firma de tokens que no sean el uso de archivos de credenciales, como la identidad de una cuenta de servicio
- Adjunta tokens firmados a las solicitudes salientes realizadas desde un stub de gRPC o una biblioteca cliente de Google API Codegen (GAPIC).
- Instrucciones para integrar los firmantes con las bibliotecas cliente de Fleet Engine
Si emites JWT desde tu código
Si no puedes usar la biblioteca de autorización para Java, debes implementar los JWT en tu propia base de código. En esta sección, se proporcionan algunos lineamientos para crear tus propios tokens. Consulta Tokens web JSON en la sección Seguridad en Fleet Engine para obtener una lista de campos y reclamos de JWT. Consulta Funciones de la cuenta de servicio para conocer las funciones de la cuenta de servicio que usa Fleet Engine. Consulta la siguiente sección para ver una lista de ejemplos de JWT para viajes a pedido o tareas programadas.
Lineamientos generales
- Usa cuentas de servicio y roles adecuados. La cuenta de servicio y el rol asociado garantizan que el usuario que solicita el token esté autorizado para ver la información a la que el token le otorga acceso. En particular, haz lo siguiente:
- Si firmas un JWT para pasarlo a un dispositivo móvil, usa la cuenta de servicio para el rol de SDK de conductor o consumidor. De lo contrario, el dispositivo móvil puede alterar y acceder a datos a los que no debería tener acceso.
- Si firmas el JWT que se usará para llamadas con privilegios, usa la cuenta de servicio con el rol de administrador de Fleet Engine correcto cuando uses ADC o JWT. De lo contrario, la operación fallará.
- Solo comparte los tokens creados. Nunca compartas las credenciales que se usaron para crear los tokens.
- En el caso de las llamadas a gRPC, el mecanismo para adjuntar el token depende del lenguaje y el framework que se usen para realizar la llamada. El mecanismo para especificar un token en una llamada HTTP es incluir un encabezado
Authorization
con un token del portador cuyo valor sea el token. - Devuelve una hora de vencimiento. Tu servidor debe mostrar un tiempo de vencimiento para el token, por lo general, en segundos.
- Si necesitas crear y firmar un JSON directamente como portador de tokens, en lugar de usar tokens de acceso de OAuth 2.0, lee las instrucciones para la autorización de cuentas de servicio sin OAuth en la documentación de Identity Developer.
Para viajes on demand
- Cuando crees la carga útil de JWT, agrega una reclamación adicional en la sección de autorización con la clave
vehicleid
otripid
establecida en el valor del ID del vehículo o del ID de viaje para el que se realiza la llamada.
Para tareas programadas
- Cuando tu servidor llama a otras APIs, los tokens también deben contener el reclamo correspondiente. Para ello, puedes hacer lo siguiente:
- Establece el valor de cada clave en
*
. - Otorga al usuario acceso a todos los
taskids
ydeliveryvehicleids
. Para ello, agrega un reclamo adicional en la sección de autorización con las clavestaskid
ydeliveryvehicleid
. - Cuando usas el asterisco (
*
) en la declaracióntaskids
, debe ser el único elemento del array.
- Establece el valor de cada clave en
Ejemplos de JWT para viajes a pedido
En esta sección, se proporcionan ejemplos de JWT para situaciones comunes si usas viajes a pedido.
Ejemplo de token para una operación de app para conductores
{
"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"
}
}
Ejemplo de token para una operación de app de consumidor
{
"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"
}
}
Ejemplos de JWT para tareas programadas
En esta sección, se proporciona un ejemplo de JWT para situaciones típicas si usas tareas programadas.
Ejemplo de token para una app de conductor
{
"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"
}
}
Ejemplo de token para una app para consumidores
{
"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"
}
}
Ejemplos de JWT para operaciones de flotas
En esta sección, se proporciona un ejemplo de JWT para una situación típica en las operaciones de flota.
Token de ejemplo para hacer un seguimiento de todas las tareas y los vehículos de una flota
El siguiente ejemplo es un token que realiza un seguimiento de todas las tareas y los vehículos de la flota desde una app basada en la Web que usa un operador. Los permisos necesarios para estas operaciones son mayores que los de las aplicaciones cliente. Consulta Configura la biblioteca de seguimiento de flotas de JavaScript para la implementación del cliente que usaría este token:
Firma el token con el rol de IAM de Cloud de
Fleet Engine Delivery Fleet Reader
.
{
"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": "*",
}
}
Método de autenticación alternativo para las operaciones del servidor de backend
Google recomienda que uses ADC para autenticar las operaciones del servidor de backend. Si no puedes usar ADC y necesitas usar JWT, consulta estos ejemplos.
Ejemplo de token para una operación de servidor de backend a pedido
{ "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": "*" } }
Ejemplo de token para una operación de servidor de backend programada
{ "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": "*" } }
Token de ejemplo para una operación programada de creación de tareas por lotes del servidor de backend
{ "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": ["*"] } }
Token de ejemplo para un servidor de backend programado por operación de vehículo de entrega
{ "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": "*" } }
¿Qué sigue?
- Verifica tu configuración para crear un vehículo de prueba y asegurarte de que tus tokens funcionen según lo previsto.
- Si deseas obtener información sobre el uso de ADC en lugar de JWT para operaciones de servidor de backend, consulta la Descripción general de seguridad.