Emitir tokens web JSON

En este documento, se explica cómo emitir tokens web JSON como parte de la habilitación del acceso de tus apps web y para dispositivos móviles a los datos de Fleet Engine. Si aún no lo hiciste, lee Tokens web JSON en la sección Seguridad en Fleet Engine. Con el servicio de Fleet Engine, puedes emitir JWT de una de las siguientes maneras:

  • Usa la biblioteca de autorización: Google recomienda que uses este enfoque cuando tu base de código esté escrita en Java. Esta biblioteca se encarga de emitir JWTs para todos los casos de uso que puedas necesitar con el servicio y simplifica en gran medida tu implementación.
  • Crea tus propios JWTs: Si no puedes usar nuestra biblioteca de JWT, deberás compilar estos en tu propio código base. En esta sección, se proporcionan varios ejemplos de JWT para cada situación.

Cómo funcionan los JWT

En el caso de los entornos no confiables, como los teléfonos celulares y los navegadores web, tu servidor de backend emite JWT que funcionan de la siguiente manera:

  • El código del cliente que se ejecuta en un entorno de baja confianza llama al código del servidor que se ejecuta en un entorno de confianza total para solicitar el JWT adecuado que se pasará a Fleet Engine.

  • Los JWTs se asocian con cuentas de servicio, por lo que las solicitudes enviadas a Fleet Engine se asocian de forma implícita con la cuenta de servicio que firmó el JWT.

  • Las declaraciones del JWT restringen aún más los recursos con los que el cliente puede operar, como vehículos, viajes o tareas específicos.

Usa la biblioteca de autorización para Java

Para usar la biblioteca de autorización de Fleet Engine para Java, visita el repositorio de GitHub. La biblioteca simplifica la construcción de JWT de Fleet Engine y los firma de forma segura. Proporciona lo siguiente:

  • Declaraciones de dependencias del proyecto
  • Una lista completa de todos los roles de la cuenta de servicio para viajes a pedido o tareas programadas
  • Mecanismos de firma de tokens que no usan archivos de credenciales, como la suplantación de una cuenta de servicio
  • Adjunta tokens firmados a las solicitudes salientes realizadas desde un stub de gRPC o una biblioteca cliente de Google API Codegen (GAPIC).
  • Instrucciones para integrar los firmantes con las bibliotecas cliente de Fleet Engine

Si emites JWTs desde tu código

Si no puedes usar la biblioteca de autorización para Java, debes implementar JWTs en tu propio código base. En esta sección, se proporcionan algunos lineamientos para crear tus propios tokens. Consulta Tokens web JSON en la sección Seguridad en Fleet Engine para obtener una lista de los campos y los reclamos de JWT. Consulta Roles de cuentas de servicio para conocer los roles de cuentas de servicio que usa Fleet Engine. Consulta la siguiente sección para ver una lista de ejemplos de JWT para viajes a pedido o tareas programadas.

Lineamientos generales

  • Usa cuentas de servicio y roles adecuados. La cuenta de servicio y el rol asociado garantizan que el usuario que solicita el token esté autorizado para ver la información a la que el token le otorga acceso. En particular, haz lo siguiente:
    • Si firmas un JWT para pasarlo a un dispositivo móvil, usa la cuenta de servicio para el rol del SDK de Driver o Consumer. De lo contrario, el dispositivo móvil puede alterar y acceder a datos a los que no debería tener acceso.
    • Si firmas el JWT que se usará para las llamadas privilegiadas, usa la cuenta de servicio con el rol correcto de administrador de Fleet Engine cuando uses ADC o JWT. De lo contrario, la operación fallará.
  • Solo comparte los tokens creados. Nunca compartas las credenciales que se usan para crear los tokens.
  • Para las llamadas de gRPC, el mecanismo para adjuntar el token depende del lenguaje y el framework que se usen para realizar la llamada. El mecanismo para especificar un token en una llamada HTTP consiste en incluir un encabezado Authorization con un token de portador cuyo valor sea el token.
  • Devuelve una hora de vencimiento. Tu servidor debe devolver una fecha y hora de vencimiento para el token, generalmente en segundos.
  • Si necesitas crear y firmar un JSON directamente como un token del portador, en lugar de usar tokens de acceso de OAuth 2.0, lee las instrucciones para la autorización de cuentas de servicio sin OAuth en la documentación para desarrolladores de Identity.

Para viajes a pedido

  • Cuando crees la carga útil del JWT, agrega un reclamo adicional en la sección de autorización con la clave vehicleid o tripid establecida en el valor del ID del vehículo o del viaje para el que se realiza la llamada.

Para tareas programadas

  • Cuando tu servidor llama a otras APIs, los tokens también deben contener el reclamo adecuado. Para ello, puedes hacer lo siguiente:
    • Establece el valor de cada clave en *.
    • Otorga al usuario acceso a todos los taskids y deliveryvehicleids. Para ello, agrega un reclamo adicional en la sección de autorización con las claves taskid y deliveryvehicleid.
    • Cuando se usa el asterisco (*) en la declaración taskids, debe ser el único elemento del array.

Ejemplos de JWT para viajes a pedido

En esta sección, se proporcionan ejemplos de JWT para situaciones comunes si usas viajes a pedido.

Ejemplo de token para una operación de la app para conductores

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_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": {
     "vehicleid": "driver_12345"
   }
}

Ejemplo de token para una operación de app de consumidor

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_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": {
     "tripid": "trip_54321"
   }
}

Ejemplos de JWT para tareas programadas

En esta sección, se proporciona un ejemplo de JWT para situaciones típicas si usas tareas programadas.

Ejemplo de token para una app de conductor

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

Ejemplo de token para una app para consumidores

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

Ejemplos de JWT para operaciones de flota

En esta sección, se proporciona un ejemplo de JWT para una situación típica en las operaciones de la flota.

Token de ejemplo para hacer un seguimiento de todas las tareas y vehículos de una flota

El siguiente ejemplo es un token que hace un seguimiento de todas las tareas y vehículos de la flota desde una app basada en la Web que usa un operador. Los permisos necesarios para estas operaciones son mayores que los de las aplicaciones cliente. Consulta Cómo configurar la biblioteca de Fleet Tracking de JavaScript para ver la implementación del cliente que usaría este token:

  • Firma el token con el rol de Fleet Engine Delivery Fleet Reader Cloud IAM.

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

Método de autenticación alternativo para las operaciones del servidor de backend

Google recomienda que uses la ADC para autenticar las operaciones del servidor de backend. Si no puedes usar ADC y necesitas usar JWT, consulta estos ejemplos.

Ejemplo de token para una operación del servidor de backend a pedido

  {
    "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": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }
  

Ejemplo de token para una operación programada del 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": "*"
       }
    }
   

Ejemplo de token para una operación de creación por lotes de tareas del servidor de backend programada

    {
      "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": ["*"]
       }
    }
  

Ejemplo de token para una operación programada del servidor de backend por vehículo de reparto

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

¿Qué sigue?