En esta sección, se explican los conceptos de autenticación y autorización con respecto a la implementación de Fleet Engine. En él, se detallan los procedimientos que debes realizar para proteger tus llamadas a funciones de Fleet Engine.
Puedes configurar las funciones que proporciona Last Mile Fleet Solution a través de Google Cloud Console. Estas APIs y SDKs requieren el uso de tokens web JSON (JWT) que se firmaron con cuentas de servicio creadas desde la consola de Cloud.
Descripción general
Como parte de su mecanismo de autorización, Fleet Engine proporciona seguridad adicional contra llamadas que se originan en entornos de baja confianza. Los entornos de baja confianza incluyen smartphones y navegadores. Además, Fleet Engine emplea el Principio de privilegio mínimo, en el que una llamada solo debe otorgar los privilegios necesarios para que complete su tarea.
Para proteger las llamadas a funciones que se originan en entornos de baja confianza, Google diseñó un mecanismo en el que el código crea un token en tu servidor de backend, que es un entorno de confianza. Cada llamada lleva una descripción de seguridad completa que luego se encripta en un JWT que pasas con la llamada desde cualquier entorno.
Principios del diseño de Authentication
El flujo de autenticación de Fleet Engine incorpora los siguientes principios de diseño.
Las funciones de IAM definen el alcance de la actividad permitida para el emisor. Por ejemplo, la función SuperUser puede realizar todas las tareas, mientras que la función SuperUser solo puede realizar actualizaciones de ubicación mínimas.
Los roles de IAM se asocian con cuentas de servicio.
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.
Las solicitudes enviadas a Fleet Engine siempre contienen un JWT.
- Debido a que los JWT están asociados con cuentas de servicio, las solicitudes enviadas a Fleet Engine se asocian de manera implícita con la cuenta de servicio asociada con el JWT.
Para solicitar el JWT adecuado que luego podrás pasar a Fleet Engine, el código que se ejecuta en un entorno de baja confianza primero debe llamar al código que se ejecuta en un entorno de confianza.
Fleet Engine realiza las siguientes verificaciones de seguridad:
Las funciones de IAM asociadas con la cuenta de servicio proporcionan la autorización correcta para que el emisor emita la llamada a la API.
Las reclamaciones de JWT pasadas en la solicitud proporcionan la autorización correcta para que el emisor opere en la entidad.
Flujo de autenticación
En el siguiente diagrama de secuencias, se muestran estos detalles del flujo de autenticación.
El administrador de la flota crea cuentas de servicio.
El administrador de la flota asigna roles de IAM específicos a las cuentas de servicio.
El administrador de la flota configura su backend con las cuentas de servicio.
La app del cliente solicita un JWT al backend del socio. El solicitante podría ser la app del conductor, la app del consumidor o una app de supervisión.
Fleet Engine 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 para leer o modificar datos, según los roles de IAM que se le asignaron durante la fase de configuración.
Configuración del proyecto de Cloud
Para configurar tu proyecto de la nube, primero crea tu proyecto 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 crear JWT que otorguen diferentes conjuntos de permisos según la función. Para reducir la posibilidad de abusos, puedes crear varias cuentas de servicio, cada una con el conjunto mínimo de funciones requeridas.
Last Mile Fleet Solution 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 la tarea. Los tokens que genera 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 de entrega de Fleet Engine
roles/fleetengine.deliveryUntrustedDriver |
Otorga permiso para actualizar la ubicación del vehículo de entrega. Los tokens que una cuenta de servicio con esta función crea por lo general se usan desde los dispositivos móviles del conductor de entrega. |
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 las tareas. Los tokens que una cuenta de servicio con esta función crea por lo general se usan desde el navegador web del consumidor de entregas. |
Superusuario de entrega de Fleet Engine
roles/fleetengine.deliverySuperUser |
Otorga permiso a todas las APIs de vehículos de entrega y tareas. Los tokens que una cuenta de servicio con esta función genera 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 vehículos y tareas de entrega y buscar tareas con un ID de seguimiento. Los tokens que genera una cuenta de servicio con este rol se suelen usar desde el navegador web del operador de la flota de entregas. |
Las organizaciones que proporcionan a sus controladores de entrega dispositivos administrados por el equipo de TI corporativo pueden aprovechar la flexibilidad que ofrece la función de usuario de controlador de confianza de Fleet Engine y elegir integrar algunas o todas las interacciones de Fleet Engine en la app para dispositivos móviles.
Las organizaciones que admiten políticas de la opción Usa tu propio dispositivo deben optar por la seguridad de la función de usuario de controlador no confiable de Fleet Engine y solo depender de la app para dispositivos móviles a fin de enviar actualizaciones de la ubicación del vehículo a Fleet Engine. Todas las demás interacciones deben originarse en los servidores de backend del cliente.
Los SDK de Driver y Consumer se basan en estos roles estándar. Sin embargo, es posible crear funciones personalizadas que permitan agrupar un conjunto arbitrario de permisos. Los SDK de Driver y Consumer mostrarán mensajes de error cuando falte un permiso necesario. Por lo tanto, te recomendamos usar el conjunto de funciones estándar que se presentó antes 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
en la consola de Google Cloud. En la lista desplegable Rol, selecciona Fleet Engine y asigna uno de los roles a la cuenta de servicio. Se recomienda indicar la cuenta asociada con cada función.
Por ejemplo, asigna un nombre significativo a la cuenta de servicio.
Para mayor comodidad, si necesitas crear 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 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
En el ejemplo anterior, 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. La nueva 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 suplantar la identidad de una cuenta de servicio).
- Adjunta tokens firmados a las solicitudes salientes realizadas desde un stub de gRPC o un cliente de GAPIC.
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. Esto requiere que tengas un conocimiento profundo de los JWT y de cómo se relacionan con Fleet Engine. Es por eso que recomendamos EN gran medida que aproveches la biblioteca de autenticación de Fleet Engine.
En 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 reclamaciones contiene información como la hora de creación del token, su tiempo de actividad, los servicios a los que el token reclama el acceso y otra información de autorización para determinar el acceso, por ejemplo, el ID del vehículo de entrega.La sección de un encabezado JWT contiene los siguientes campos:
| Campo | Descripción |
|---|---|
| alg | El algoritmo que se usará. `RS256`. |
| typ | Es el tipo de token. “JWT”. |
| niño | 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 la 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 su cuenta de servicio, en este caso https://fleetengine.googleapis.com/ |
| iat | La marca de tiempo de 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, es posible que el servidor informe un error. |
| exp | La marca de tiempo de cuándo 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 de más de una hora después. |
| autorización | Según el caso de uso, puede contener "deliveryvehicleid", "trackingid", "taskid" o "taskids". |
Crear un token JWT hace referencia a firmarlo. Si deseas obtener instrucciones y muestras de código para crear y firmar el JWT, consulta Autorización de cuenta de servicio sin OAuth. Luego, puedes adjuntar un token creado a las llamadas de gRPC o a otros métodos que se usen para acceder a Fleet Engine.
Reclamaciones de JWT
Last Mile Fleet Solution usa reclamaciones privadas. Usar reclamaciones privadas garantiza que solo los clientes autorizados puedan acceder a sus propios datos. Por ejemplo, cuando tu backend emite un token web JSON para el dispositivo móvil de un repartidor, ese token debería contener la reclamación deliveryvehicleid con el valor del ID del vehículo de entrega de ese conductor. Luego, según la función del conductor, los tokens habilitan el acceso solo para el ID del vehículo de entrega específico y no para cualquier otro ID de vehículo arbitrario.
Last Mile Fleet Solution 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 para llamar aBatchCreateTasksAPI. 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 reclamosdelivervehicleid,trackingidnitaskid.trackingid: Se usa para llamar aSearchTasksAPI. La reclamación debe coincidir con el ID de seguimiento de la solicitud. No incluyas reclamacionesdelivervehicleid,taskidnitaskids.
El token también debe contener la reclamación correspondiente 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 de Autorización de cuenta de servicio sin OAuth en la documentación de Identity Developer.
El mecanismo para conectar el token a una llamada de gRPC 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 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ío o rendimiento de flota.
En el siguiente ejemplo, se muestra un token para una operación por tarea desde el 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 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": {
"deliveryvehicleid": "*"
}
}
En el siguiente ejemplo, se muestra un token para clientes de usuario final:
{
"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 del 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
kiddel encabezado, especifica el ID de la clave privada de tu cuenta de servicio. Puedes encontrar este valor en el campoprivate_key_iddel archivo JSON de tu cuenta de servicio. - En los campos
issysub, especifica la dirección de correo electrónico de tu cuenta de servicio. Puedes encontrar este valor en el campoclient_emaildel archivo JSON de tu cuenta de servicio. - En el campo
aud, especifica https://SERVICE_NAME/. - Para el campo
iat, especifica la marca de tiempo de cuando se creó el token, 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, es posible que el servidor informe un error. - Para el campo
exp, especifica la marca de tiempo de cuándo vence el token, en segundos a partir de las 00:00:00 UTC del 1 de enero de 1970. El valor recomendado esiat+ 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 el rol de consumidor o conductor de entrega. De lo contrario, el dispositivo móvil o el usuario final podrán modificar o ver información a la que no deberían tener acceso.