Tokens web JSON

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 muestra un JWT codificado y firmado digitalmente para usarlo con las solicitudes posteriores. Este proceso autentica al usuario y lo autoriza a acceder a rutas, servicios y recursos según el rol de su cuenta.

Para las llamadas a métodos de API desde entornos de baja confianza, Fleet Engine requiere el uso de tokens web JSON (JWT) firmados por una cuenta de servicio adecuada. Los entornos de baja confianza incluyen smartphones y navegadores. Un JWT se origina en tu servidor, que es un entorno completamente confiable. El JWT se firma, encripta y pasa al cliente para interacciones posteriores con el servidor hasta que venza o ya no sea válido.

Tu backend debe autenticarse y autorizarse en Fleet Engine con los mecanismos estándar de las credenciales predeterminadas de la aplicación. Asegúrate de usar JWTs firmados por una cuenta de servicio adecuada. Para obtener una lista de los roles de las cuentas de servicio, consulta los roles de la cuenta de servicio de Fleet Engine en Conceptos básicos de Fleet Engine.

En cambio, tu backend debe autenticarse y autorizarse en Fleet Engine con mecanismos estándar de credenciales predeterminadas de la aplicación.

A diferencia de las claves de API, los JWT son de corta duración 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 cuenta de servicio en esta guía.

Elementos JWT

Los JWT contienen un encabezado y una sección de reclamos. La sección de encabezado contiene información como la clave privada obtenida de las cuentas de servicio y el algoritmo de encriptación. La sección de reclamos contiene información como la hora de creación del JWT, el tiempo de vida útil, los servicios a los que el JWT reclama acceso y otra información de autorización para definir el acceso, por ejemplo, el ID del vehículo de entrega.

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

El ID de clave privada de tu cuenta de servicio Puedes encontrar este valor en el campo private_key_id del archivo JSON de tu cuenta de servicio. Asegúrate de usar una clave de una cuenta de servicio con el nivel correcto de permisos.
Campos de reclamos 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 del archivo JSON de tu cuenta de servicio

sub

La dirección de correo electrónico de tu cuenta de servicio, que se encuentra en el campo client_email del archivo JSON de tu cuenta de servicio

aud

El SERVICE_NAME de tu cuenta de servicio, en este caso https://fleetengine.googleapis.com/

iat

La marca de tiempo de la creación del JWT, especificada en segundos transcurridos desde las 00:00:00 UTC, January 1, 1970. Espera 10 minutos para el sesgo. Si la marca de tiempo es demasiado antigua o futura, es posible que el servidor informe un error.

exp

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 superior a una hora en el futuro.

autorización

Según el caso de uso, puede contener deliveryvehicleid, trackingid, taskid o taskids.

Si especificas 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": ["*"]

Declaraciones 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 JWT permiten el acceso solo para el ID del 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 esta declaración, ya sea que se opere en un viaje o en un vehículo. El backend de Fleet Engine se asegura de que el vehículo esté asociado con el viaje solicitado antes de realizar la modificación.
    • El JWT puede abarcar las operaciones del vehículo y del viaje, incluso si no es obligatorio, lo que puede simplificar la implementación de la firma de JWT.
  • tripid:
    • El SDK para consumidores siempre usa este reclamo.
    • El JWT puede abarcar las operaciones de vehículos y viajes, incluso si no es obligatorio, lo que puede simplificar la implementación de la firma de tokens.

Tareas programadas

  • deliveryvehicleid

    Úsalo cuando llames a las APIs de cada vehículo de entrega.

  • taskid

    Úsalo cuando llames a las APIs por tarea.

  • taskids

    Úsalo cuando llames a BatchCreateTasksAPI. Esta declaración debe estar en forma de array, y el array debe contener todos los IDs de tareas necesarios para completar la solicitud. No incluyas declaraciones delivervehicleid, trackingid ni taskid.

  • trackingid

    Úsalo cuando llames a GetTaskTrackingInfoAPI. El reclamo debe coincidir con el ID de seguimiento de la solicitud. No incluyas declaraciones delivervehicleid, taskid ni taskids.

¿Qué sigue?