Por el momento, la solución para flotas de último tramo solo está disponible para determinados clientes. Comunícate con Ventas para obtener más información.

Se usó la API de Cloud Translation para traducir esta página.

Autenticación y autorización

En esta sección, se explican los conceptos de autenticación y autorización con respecto a la integración en Fleet Engine.

Puedes configurar las capacidades que proporciona la solución de flota de red de acceso a través de Google Cloud Console. Los SDK de Fleet Engine requieren el uso de tokens web JSON (JWT) que estén firmados por una cuenta de servicio apropiada.

Descripción general

Los backends de clientes que se autentican y autorizan en Fleet Engine deben usar el mecanismo estándar de credenciales predeterminadas de la aplicación.

Fleet Engine también recibe llamadas que se originan en entornos de baja confianza, como smartphones y navegadores. Para proteger las claves secretas de las cuentas de servicio que solo son adecuadas para entornos de confianza, se espera que los backends de los clientes generen tokens web JSON (JWT) firmados con reclamaciones adicionales específicas de Fleet Engine que, luego, pueden emitirse a entornos no confiables, como los teléfonos celulares.

Principios del diseño de autenticación

El flujo de autenticación de Fleet Engine incorpora los siguientes principios de diseño.

Los roles de IAM definen un conjunto de permisos en los recursos permitidos para una principal. Por ejemplo, las funciones de administrador pueden hacer todo con las credenciales predeterminadas de la aplicación, mientras que la función de controlador no confiable* solo puede actualizar la ubicación del vehículo y se restringe a usar JWT para la autenticación y autorización.
Para los entornos que no son de confianza, las reclamaciones de JWT restringen aún más las entidades en las que puede operar el emisor. Pueden ser tareas o vehículos de entrega específicos.
El código que se ejecuta en un entorno de confianza baja primero debe llamar al código que se ejecuta en un entorno confiable para emitir un JWT.
Fleet Engine realiza las siguientes verificaciones de seguridad en las llamadas a la API de un recurso:
1. La principal que realiza la llamada tiene los permisos adecuados (a través de la asignación de roles) para realizar la acción en el recurso.
2. Para las funciones que no son de administrador, las reclamaciones de JWT pasadas en la solicitud proporcionan el permiso necesario para el recurso.

Flujo de autenticación

En el siguiente diagrama de secuencias, se muestran los detalles del flujo de autenticación.

El administrador de la flota crea cuentas de servicio.
El administrador de la flota asigna roles específicos de IAM a las cuentas de servicio.
El administrador de la flota configura su backend con las cuentas de servicio y las credenciales predeterminadas de la aplicación.
La app cliente solicita un JWT al backend del cliente. El solicitante puede ser la app de Driver, la app del consumidor o una app de supervisión.
El backend del cliente firma y emite un JWT para la cuenta de servicio correspondiente. La app cliente recibe el JWT.
La app cliente usa el JWT para conectarse a Fleet Engine a fin de leer o modificar datos, según las funciones de IAM que se le asignaron durante la fase de configuración.

Diagrama de secuencia de autenticación

Configuración del proyecto de Cloud

Para configurar tu proyecto de la nube, primero créalo y, luego, crea cuentas de servicio.

Para crear tu proyecto de Google Cloud, sigue estos pasos:

Crea un proyecto de Google Cloud con la consola de Google Cloud.
En el panel de APIs y servicios, habilita la API de Local Rides and Deliveries.

Cuentas de servicio y roles de IAM

Una cuenta de servicio es un tipo especial de cuenta que usa una aplicación, en lugar de una persona. Por lo general, se usa una cuenta de servicio para acuñar JWT que otorgan diferentes conjuntos de permisos según la función. Para reducir la posibilidad de abuso, puedes crear varias cuentas de servicio, cada una con el conjunto mínimo de roles necesarios ().

La solución de flota de red de acceso usa los siguientes roles:

Rol	Descripción
Usuario de controlador de confianza de entrega de Fleet Engine `roles/fleetengine.deliveryTrustedDriver`	Otorga permiso para crear y actualizar vehículos y tareas de entrega, incluida la actualización de la ubicación del vehículo de entrega y el estado o el resultado de las tareas. Los tokens que crea una cuenta de servicio con esta función se suelen usar desde los dispositivos móviles del repartidor o desde tus servidores de backend.
Usuario de controlador no confiable para la entrega de Fleet Engine `roles/fleetengine.deliveryUntrustedDriver`	Otorga permiso para actualizar la ubicación del vehículo de entrega. Los tokens que crea una cuenta de servicio con esta función se suelen usar desde los dispositivos móviles del repartidor.
Usuario consumidor de entrega de Fleet Engine `roles/fleetengine.deliveryConsumer`	Otorga permiso para buscar tareas mediante un ID de seguimiento y leer, pero no actualizar la información de la tarea. Los tokens que crea una cuenta de servicio con esta función se suelen usar desde el navegador web de un consumidor de entregas.
Administrador de entrega de Fleet Engine `roles/fleetengine.deliveryAdmin`	Otorga permisos de lectura y escritura para los recursos de entrega. Las principales con este rol no necesitan usar JWT y, en su lugar, deben usar las credenciales predeterminadas de la aplicación. Se ignoran las reclamaciones personalizadas de JWT. Esta función debe restringirse a entornos de confianza (backend del cliente).
~~Superusuario de entrega de Flet Engine~~ (OBSOLETO) `roles/fleetengine.deliverySuperUser`	Otorga permiso a todas las APIs de vehículos y tareas de entrega. Los tokens que crea una cuenta de servicio con esta función, por lo general, se usan desde tus servidores de backend.
Lector de flota de entrega de Fleet Engine `roles/fleetengine.deliveryFleetReader`	Otorga permiso para leer tareas y vehículos de entrega, y buscar tareas mediante un ID de seguimiento. Los tokens que crea una cuenta de servicio con esta función se suelen usar desde el navegador web de un operador de flota de entregas.

Las organizaciones que proporcionan a sus repartidores dispositivos administrados por la TI corporativa pueden aprovechar la flexibilidad que ofrece la función Usuario de conductor confiable de Fleet Engine y elegir integrar algunas o todas las interacciones de Fleet Engine en la aplicación para dispositivos móviles.

Las organizaciones que admiten las políticas Usa tu propio dispositivo deben optar por la seguridad de la función Usuario de conductor no confiable de Fleet Engine y solo depender de la app para dispositivos móviles para enviar actualizaciones de la ubicación del vehículo a Fleet Engine. Todas las demás interacciones deben provenir de los servidores de backend del cliente.

Los SDK del controlador y del consumidor se basan en estas funciones estándar. Sin embargo, es posible crear funciones personalizadas que permitan agrupar un conjunto arbitrario de permisos. Los SDK para consumidores y controladores mostrarán mensajes de error cuando falte un permiso necesario. Por lo tanto, recomendamos enfáticamente usar el conjunto estándar de funciones que se presentó arriba, en lugar de las funciones personalizadas.

Crea una cuenta de servicio

Puedes crear una cuenta de servicio mediante la pestaña IAM & Admin > Service Accounts de Google Cloud Console. En la lista desplegable Función, selecciona Fleet Engine y asigna una de las funciones a la cuenta de servicio. Se recomienda indicar la cuenta que está asociada con cada función. Por ejemplo, asigna un nombre significativo a la cuenta de servicio.

Para mayor comodidad, si necesitas acuñar JWT para clientes que no son de confianza, agregar usuarios a la función de creador de tokens de cuentas de servicio les permite crear tokens con las herramientas de línea de comandos de gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Donde my-user@example.com es el correo electrónico que se usa para autenticarse con gcloud (gcloud auth list --format='value(account)').

Biblioteca de autenticación de Fleet Engine

Fleet Engine usa JWT para restringir el acceso a las APIs de Fleet Engine en entornos no confiables. La biblioteca de autenticación de Fleet Engine, disponible en GitHub, simplifica la construcción de los JWT de Fleet Engine y los firma de forma segura.

La biblioteca proporciona los siguientes beneficios:

Simplifica el proceso de creación de tokens de Fleet Engine.
Proporciona mecanismos de firma de tokens distintos del uso de archivos de credenciales (como la identidad de una cuenta de servicio).

Crea un token web JSON (JWT) para la autorización

Cuando no se usa la biblioteca de autenticación de Fleet Engine, los JWT deben crearse directamente dentro de tu base de código. Para ello, debes comprender en profundidad los JWT y cómo se relacionan con Fleet Engine. Por este motivo, recomendamos ALTAMENTE aprovechar la biblioteca de autenticación de Fleet Engine.

Dentro de Fleet Engine, los JWT proporcionan autenticación de corta duración y garantizan que los dispositivos solo puedan modificar vehículos o tareas para los que estén autorizados. Los JWT contienen un encabezado y una sección de reclamación. La sección del encabezado contiene información como la clave privada que se usará (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 token, el tiempo de actividad del token, los servicios a los que el token reclama acceso y otra información de autorización para limitar el acceso; por ejemplo, el ID del vehículo de entrega.

Una sección de encabezado JWT contiene los siguientes campos:

Campo	Descripción
`alg`	El algoritmo que se usará. `RS256`:
`typ`	El tipo de token. “JWT”.
`kid`	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 correcto de permisos.

Una sección de reclamaciones de JWT contiene los siguientes campos:

Campo	Descripción
`iss`	La dirección de correo electrónico de tu cuenta de servicio.
`sub`	La dirección de correo electrónico 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 cuando se creó el token, especificada en segundos transcurridos desde las 00:00:00 UTC del 1 de enero de 1970. Espera 10 minutos para el sesgo. Si la marca de tiempo es demasiado lejana en el pasado o en el futuro, el servidor podría informar un error.
`exp`	Es la marca de tiempo de cuando vence el token, especificada en segundos transcurridos desde las 00:00:00 UTC del 1 de enero de 1970. La solicitud falla si la marca de tiempo es dentro de más de una hora en el futuro.
`authorization`	Según el caso de uso, puede contener "deliveryvehicleid", "trackingid", "taskid" o "taskids".

Crear un token JWT hace referencia a firmarlo. Si quieres obtener instrucciones y muestras de código para crear y firmar el JWT, consulta Autorización de la cuenta de servicio sin OAuth. Luego, puedes adjuntar un token creado a las llamadas de gRPC o a otros métodos utilizados para acceder a Fleet Engine.

Reclamaciones de JWT

La solución de flota de red de acceso usa reclamaciones privadas. Usar reclamaciones privadas garantiza que solo los clientes autorizados accedan a sus datos. Por ejemplo, cuando tu backend emite un token web JSON para el dispositivo móvil de un repartidor, ese token debe contener la reclamación deliveryvehicleid con el valor del ID del vehículo de entrega de ese conductor. Luego, según el rol del conductor, los tokens habilitan el acceso solo para el ID específico del vehículo de entrega y no para ningún otro ID de vehículo arbitrario.

La solución de flota de red de acceso usa las siguientes reclamaciones privadas:

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 forma de array, y este debe contener todos los IDs de tarea necesarios para completar la solicitud. No incluyas las reclamaciones delivervehicleid, trackingid ni taskid.
trackingid: Se usa cuando se llama a GetTaskTrackingInfoAPI. La reclamación debe coincidir con el ID de seguimiento de la solicitud. No incluyas las reclamaciones delivervehicleid, taskid ni taskids.

El token también debe contener la reclamación adecuada cuando llamas a las APIs desde tu servidor de backend, pero puedes usar el valor especial de un asterisco (*) para las reclamaciones deliveryvehicleid, taskid y trackingid. El asterisco (*) también se puede usar en la reclamación taskids, pero debe ser el único elemento del array.

Si deseas 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 Autorización de cuenta de servicio sin OAuth en la documentación de Identity Developer.

El mecanismo para adjuntar el token a una llamada de gRPC depende del lenguaje y el framework que se usan para realizar la llamada. El mecanismo para especificar un token en una llamada HTTP es incluir un encabezado de autorización con un token del portador cuyo valor sea el token, como se indica en las notas de autorización para casos de uso individuales de seguimiento de envíos o de rendimiento de flotas.

En el siguiente ejemplo, se muestra un token para una operación por tarea de tu 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": {
         "taskid": "*"
       }
    }

En el siguiente ejemplo, se muestra un token para una operación de creación de tareas por lotes desde tu 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": ["*"]
       }
    }

En el siguiente ejemplo, se muestra un token para una operación por vehículo de entrega de tu 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": {
         "deliveryvehicleid": "*"
       }
    }

En el siguiente ejemplo, se muestra un token para clientes usuarios finales:

    {
      "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"
       }
    }

En el siguiente ejemplo, se muestra un token para tu app de controlador:

    {
      "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"
       }
    }

En el campo kid del encabezado, especifica 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.
Para los campos iss y sub, especifica la dirección de correo electrónico de tu cuenta de servicio. Puedes encontrar este valor en el campo client_email del archivo JSON de tu cuenta de servicio.
En el campo aud, especifica https://SERVICE_NAME/.
En el campo iat, especifica la marca de tiempo de la creación del token, expresado en segundos transcurridos desde las 00:00:00 UTC del 1 de enero de 1970. Espera 10 minutos para el sesgo. Si la marca de tiempo es demasiado lejana en el pasado o en el futuro, el servidor podría informar un error.
En el campo exp, especifica la marca de tiempo de vencimiento del token, en segundos desde las 00:00:00 UTC del 1 de enero de 1970. El valor recomendado es iat + 3,600.

Cuando firmes el token que se pasará a un dispositivo móvil o usuario final, asegúrate de usar el archivo de credenciales para la función de Conductor de entrega o Consumidor. De lo contrario, el dispositivo móvil o el usuario final podrá modificar o ver información a la que no debería tener acceso.