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 solicitudes posteriores. Este proceso autentica al usuario y lo autoriza a acceder a rutas, servicios y recursos según su rol de cuenta.

Fleet Engine requiere el uso de tokens web JSON (JWTs) 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 interacciones posteriores con el servidor hasta que vence o ya no es válido.

Detalles clave

A diferencia de las claves de API, los JWTs 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 JWTs, consulta Tokens web JSON en Wikipedia. Para obtener detalles sobre los roles de acceso, consulta Roles de la cuenta de servicio en esta guía.

Elementos de JWT

Los JWTs contienen un encabezado y una sección de reclamaciones. 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 reclamaciones contiene información como la hora de creación del JWT, el tiempo de actividad, los servicios a los que el JWT reclama acceso y otra información de autorización para definir el alcance del 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 Cloud de Fleet Engine.

Campos del encabezado JWT

Campo

Descripción

alg

El algoritmo que se usará. `RS256`.

typ

El tipo de token. `JWT`.

niño

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

La marca de tiempo cuando se creó el JWT, especificada en segundos transcurridos desde las 00:00:00 UTC, January 1, 1970. Permite 10 minutos para el sesgo. Si la marca de tiempo está demasiado lejos en el pasado o en el futuro, el servidor podría informar un error.

exp

La marca de tiempo cuando 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 especificas taskids, el alcance de autorización debe ser un array en una de las siguientes formas:

"taskids": ["task_id_one","task_id_two"]

o

"taskids": ["*"]

Reclamaciones de JWT de Fleet Engine

Fleet Engine usa reclamaciones privadas. El uso de reclamaciones privadas 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 la reclamación vehicleid o la deliveryvehicleid reclamación 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 del vehículo específico y no para ningún otro ID de vehículo arbitrario.

Fleet Engine usa las siguientes reclamaciones privadas:

Viajes a pedido

  • vehicleid:
    • El SDK de Driver siempre usa esta reclamación, ya sea que opere en un viaje o 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 de vehículos y viajes incluso si no es necesario, lo que puede simplificar la implementación de la firma de JWT.
  • tripid:
    • El SDK de Consumer siempre usa esta reclamación.
    • El JWT puede abarcar operaciones de vehículos y viajes, incluso si no es necesario, lo que puede simplificar la implementación de la firma de tokens implementación.

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. Esta reclamación debe estar en formato de array, y el array debe contener todos los IDs de tarea necesarios para completar la solicitud. No incluyas reclamaciones delivervehicleid, trackingid ni taskid.

  • trackingid

    Se usa cuando se llama a la GetTaskTrackingInfoAPI. La reclamación debe coincidir con el ID de seguimiento en la solicitud. No incluyas reclamaciones delivervehicleid, taskid ni taskids.

¿Qué sigue?