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 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 su rol de cuenta.

Fleet Engine requiere el uso de tokens web JSON (JWT) para las llamadas de método de la API desde entornos de bajo nivel de confianza: smartphones y navegadores.

Un JWT se origina en tu servidor, se firma, se encripta y se pasa al cliente para las interacciones posteriores con el servidor hasta que venza o deje de ser válido.

Detalles clave

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 cuentas de servicio en esta guía.

Elementos de JWT

Los JWT contienen un encabezado y una sección de reclamación. 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 reclamación 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 de encabezado de 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 del archivo JSON de tu 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 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 en la que 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 es demasiado antigua o futura, es posible que el servidor informe un error.

exponencial

La marca de tiempo en la que vence el JWT, especificada en segundos transcurridos desde el 00:00:00 UTC, January 1, 1970. La solicitud falla si la marca de tiempo es de 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 permiso 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 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 JSON Web Token para el dispositivo móvil de un conductor, debe contener la reclamación vehicleid o la reclamación deliveryvehicleid con el valor del ID del vehículo de ese conductor. Luego, según el rol del conductor, los JWT 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 las siguientes reclamaciones privadas:

Viajes on demand

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

    Se usa cuando se llama a las APIs por vehículo de entrega.

  • taskid

    Se usa cuando se llama a la API de Tasks.

  • taskids

    Se usa cuando se llama a BatchCreateTasksAPI. Esta reclamación debe tener el formato de un array, y este debe contener todos los IDs de tareas necesarios para completar la solicitud. No incluyas afirmaciones de 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 de delivervehicleid, taskid ni taskids.

¿Qué sigue?