Last Mile Fleet Solution n'est actuellement disponible que pour certains clients. Contactez le service commercial pour en savoir plus.

Cette page a été traduite par l'API Cloud Translation.

Authentification et autorisation

Cette section explique les concepts d'authentification et d'autorisation concernant l'intégration à Fleet Engine.

Vous pouvez configurer les fonctionnalités fournies par Last Mile Fleet Solution via la console Google Cloud. Les SDK Fleet Engine nécessitent l'utilisation de jetons Web JSON (JWT) qui ont été signés par un compte de service approprié.

Présentation

Les backends des clients qui s'authentifient et autorisent l'utilisation de Fleet Engine doivent utiliser des mécanismes standards d'identifiants par défaut de l'application.

Fleet Engine reçoit également des appels provenant d'environnements peu fiables tels que les smartphones et les navigateurs. Pour protéger les clés secrètes de compte de service adaptées uniquement aux environnements de confiance, les backends des clients doivent générer des jetons Web JSON (JWT) signés avec des revendications supplémentaires spécifiques à Fleet Engine, qui peuvent ensuite être émises pour des environnements non approuvés tels que des téléphones mobiles.

Principes de conception de l'authentification

Le flux d'authentification de Fleet Engine intègre les principes de conception suivants.

Les rôles IAM définissent un ensemble d'autorisations sur les ressources autorisées pour un compte principal. Par exemple, les rôles Admin peuvent tout faire avec les identifiants par défaut de l'application, tandis que le rôle de Conducteur non approuvé* ne peut mettre à jour que l'emplacement du véhicule et se limite à l'utilisation de jetons JWT pour l'authentification et l'autorisation.
Pour les environnements non approuvés, les revendications JWT limitent davantage les entités sur lesquelles l'appelant peut opérer. Il peut s'agir de tâches spécifiques ou de véhicules de livraison.
Le code exécuté dans un environnement peu fiable doit d'abord appeler le code exécuté dans un environnement approuvé pour émettre un jeton JWT.
Fleet Engine effectue les contrôles de sécurité suivants sur les appels d'API d'une ressource:
1. Le compte principal appelant dispose des autorisations appropriées (via l'attribution de rôles) pour l'action sur la ressource.
2. Pour les rôles non-administrateur, les revendications JWT transmises dans la requête fournissent l'autorisation nécessaire pour la ressource.

Flux d'authentification

Le schéma séquentiel suivant illustre les détails du flux d'authentification.

L'administrateur du parc crée les comptes de service.
L'administrateur du parc attribue des rôles IAM spécifiques aux comptes de service.
L'administrateur du parc configure son backend avec les comptes de service et les identifiants par défaut de l'application.
L'application cliente demande un jeton JWT au backend du client. Le demandeur peut être l'application Pilote, l'application grand public ou une application de surveillance.
Le backend client signe et émet un jeton JWT pour le compte de service correspondant. L'application cliente reçoit le jeton JWT.
L'application cliente utilise le jeton JWT pour se connecter à Fleet Engine afin de lire ou de modifier des données, en fonction des rôles IAM qui lui ont été attribués lors de la phase de configuration.

Schéma de la séquence d'authentification

Configurer un projet Cloud

Pour configurer votre projet cloud, commencez par créer votre projet, puis créez des comptes de service.

Pour créer votre projet Google Cloud, procédez comme suit:

Créer un projet Google Cloud à l'aide de la console Google Cloud
À l'aide du tableau de bord des API et des services, activez l'API Local Rides and Deliveries.

Comptes de service et rôles IAM

Un compte de service est un type particulier de compte utilisé par une application plutôt que par une personne. En règle générale, un compte de service est utilisé pour créer des jetons JWT qui accordent différents ensembles d'autorisations en fonction du rôle. Pour réduire le risque d'abus, vous pouvez créer plusieurs comptes de service, chacun avec l'ensemble minimal de rôles requis ().

Last Mile Fleet Solution utilise les rôles suivants:

Rôle	Description
Utilisateur de confiance Fleet Engine Delivery `roles/fleetengine.deliveryTrustedDriver`	Permet de créer et de mettre à jour des tâches et des véhicules de livraison, y compris de mettre à jour l'emplacement du véhicule de livraison et l'état ou le résultat des tâches. Les jetons générés par un compte de service doté de ce rôle sont généralement utilisés à partir des appareils mobiles de votre livreur ou de vos serveurs backend.
Utilisateur non approuvé Fleet Engine Delivery `roles/fleetengine.deliveryUntrustedDriver`	Accorde l'autorisation de mettre à jour l'emplacement du véhicule de livraison. Les jetons générés par un compte de service avec ce rôle sont généralement utilisés à partir des appareils mobiles de votre livreur.
Utilisateur consommateur Fleet Engine Delivery `roles/fleetengine.deliveryConsumer`	Octroie l'autorisation de rechercher des tâches à l'aide d'un ID de suivi et de lire les informations sur les tâches, mais pas de les mettre à jour. Les jetons générés par un compte de service doté de ce rôle sont généralement utilisés à partir du navigateur Web d'un consommateur.
Administrateur Fleet Engine Delivery<> `roles/fleetengine.deliveryAdmin`	Accorde une autorisation de lecture et d'écriture pour les ressources de diffusion. Les comptes principaux dotés de ce rôle n'ont pas besoin d'utiliser de jetons JWT, mais doivent plutôt utiliser les identifiants par défaut de l'application. Les revendications JWT personnalisées sont ignorées. Ce rôle doit être limité aux environnements approuvés (backend client).
~~Super-utilisateur Fleet Engine Delivery~~ (OBSOLÈTE) `roles/fleetengine.deliverySuperUser`	Accorde l'autorisation à toutes les API de tâches et de véhicules de livraison. Les jetons générés par un compte de service doté de ce rôle sont généralement utilisés à partir de vos serveurs backend.
Lecteur de parc Fleet Engine Delivery `roles/fleetengine.deliveryFleetReader`	Permet de lire les tâches et les véhicules de livraison, et de rechercher des tâches à l'aide d'un ID de suivi. Les jetons générés par un compte de service doté de ce rôle sont généralement utilisés à partir du navigateur Web d'un opérateur de flotte de livraisons.

Les entreprises qui fournissent à leurs livreurs des appareils gérés par le service informatique peuvent profiter de la flexibilité offerte par le rôle Utilisateur de confiance Fleet Engine et choisir d'intégrer tout ou partie des interactions Fleet Engine dans l'application mobile.

Les organisations qui acceptent les règles d'utilisation de votre propre appareil doivent garantir la sécurité du rôle "Conducteur non approuvé Fleet Engine" et ne faire appel qu'à l'application mobile pour envoyer les mises à jour de la position des véhicules à Fleet Engine. Toutes les autres interactions doivent provenir des serveurs backend du client.

Les SDK pilote et client s'articulent autour de ces rôles standards. Cependant, il est possible de créer des rôles personnalisés permettant de regrouper un ensemble arbitraire d'autorisations. Les SDK Driver et grand public affichent des messages d'erreur lorsqu'une autorisation requise est manquante. Par conséquent, nous vous recommandons vivement d'utiliser l'ensemble de rôles standard présenté ci-dessus plutôt que les rôles personnalisés.

Créer un compte de service

Vous pouvez créer un compte de service à l'aide de l'onglet IAM & Admin > Service Accounts de la console Google Cloud. Dans la liste déroulante "Rôle", sélectionnez Fleet Engine et attribuez l'un des rôles au compte de service. Il est recommandé d'indiquer le compte associé à chaque rôle. Par exemple, attribuez un nom explicite au compte de service.

Pour plus de commodité, si vous devez générer des jetons JWT pour des clients non approuvés, l'ajout d'utilisateurs au rôle Créateur de jetons du compte de service leur permet de générer des jetons à l'aide des outils de ligne de commande gcloud.

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

Où my-user@example.com est l'adresse e-mail utilisée pour l'authentification avec gcloud (gcloud auth list --format='value(account)').

Bibliothèque d'authentifications Fleet Engine

Fleet Engine utilise des jetons JWT pour limiter l'accès aux API Fleet Engine dans des environnements non approuvés. La bibliothèque d'authentification Fleet Engine, disponible sur GitHub, simplifie la construction des jetons JWT Fleet Engine et les signe de manière sécurisée.

Elle offre les avantages suivants:

Simplifie le processus de création de jetons Fleet Engine.
Fournit des mécanismes de signature de jetons autres que l'utilisation de fichiers d'identifiants (par exemple, l'emprunt d'identité d'un compte de service).

Créer un jeton Web JSON (JWT) pour l'autorisation

Lorsque vous n'utilisez pas la bibliothèque d'authentification Fleet Engine, les jetons JWT doivent être créés directement dans votre codebase. Pour cela, vous devez bien comprendre les jetons JWT et leur lien avec Fleet Engine. C'est pourquoi nous vous recommandons vivement de tirer parti de la bibliothèque d'authentification Fleet Engine.

Dans Fleet Engine, les jetons JWT fournissent une authentification de courte durée et garantissent que les appareils ne peuvent modifier que les véhicules ou les tâches pour lesquels ils sont autorisés. Les jetons JWT contiennent un en-tête et une section de revendication. La section d'en-tête contient des informations telles que la clé privée à utiliser (obtenue auprès des comptes de service) et l'algorithme de chiffrement. La section de revendication contient des informations telles que l'heure de création du jeton, sa valeur TTL, les services auxquels le jeton demande l'accès et d'autres informations d'autorisation permettant de limiter l'accès (par exemple, l'ID du véhicule de livraison).

Une section d'en-tête JWT contient les champs suivants:

Champ	Description
alg	Algorithme à utiliser. "RS256".
typ	Type de jeton. "JWT".
enfant	ID de la clé privée de votre compte de service. Vous trouverez cette valeur dans le champ "private_key_id" du fichier JSON de votre compte de service. Veillez à utiliser une clé provenant d'un compte de service disposant des autorisations appropriées.

Une section des revendications JWT contient les champs suivants:

Champ	Description
iss	Adresse e-mail de votre compte de service.
Pub/Sub.	Adresse e-mail de votre compte de service.
aud	le nom de service (SERVICE_NAME) de votre compte de service (ici, https://fleetengine.googleapis.com/) ;
iat	Horodatage de la création du jeton, spécifié en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. Prévoyez 10 minutes pour le décalage. Si l'horodatage est trop éloigné dans le passé ou futur, le serveur peut signaler une erreur.
exp	Code temporel d'expiration du jeton, spécifié en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. La requête échoue si l'horodatage est postérieur à plus d'une heure.
autorisation	Selon le cas d'utilisation, peut contenir "deliveryvehicleid", "trackingid", "taskid" ou "taskid".

La génération d'un jeton JWT correspond à sa signature. Pour obtenir des instructions et des exemples de code pour la création et la signature du jeton JWT, consultez la section Autorisation de compte de service sans OAuth. Vous pouvez ensuite associer un jeton signé aux appels gRPC ou à d'autres méthodes utilisées pour accéder à Fleet Engine.

Revendications JWT

Last Mile Fleet Solution utilise des revendications privées. L'utilisation de revendications privées garantit que seuls les clients autorisés peuvent accéder à leurs propres données. Par exemple, lorsque votre backend émet un jeton Web JSON pour l'appareil mobile d'un livreur, ce jeton doit contenir la revendication deliveryvehicleid avec la valeur de l'ID du véhicule de livraison de ce chauffeur. Ensuite, en fonction du rôle de conducteur, les jetons n'autorisent l'accès que pour l'ID de véhicule fourni et non pour tout autre ID de véhicule arbitraire.

Last Mile Fleet Solution utilise les revendications privées suivantes:

deliveryvehicleid : à utiliser lors de l'appel d'API par véhicule de livraison.
taskid : à utiliser lors de l'appel d'API par tâche.
taskids : à utiliser lorsque vous appelez BatchCreateTasksAPI. Cette revendication doit se présenter sous forme de tableau, et celui-ci doit contenir tous les ID de tâche nécessaires au traitement de la requête. N'incluez pas les revendications delivervehicleid, trackingid ou taskid.
trackingid : à utiliser lors de l'appel de GetTaskTrackingInfoAPI. La revendication doit correspondre à l'ID de suivi de la requête. N'incluez pas les revendications delivervehicleid, taskid ou taskids.

Le jeton doit également contenir la revendication appropriée lorsque vous appelez des API à partir de votre serveur backend, mais vous pouvez utiliser la valeur spéciale d'un astérisque ("*") pour les revendications deliveryvehicleid, taskid et trackingid. L'astérisque ("*") peut également être utilisé dans la revendication taskids, mais il doit s'agir du seul élément du tableau.

Si vous souhaitez créer et signer un fichier JSON directement en tant que support de jeton plutôt que d'utiliser des jetons d'accès OAuth 2.0, consultez les instructions concernant l'autorisation via un compte de service sans OAuth dans la documentation sur l'identité pour les développeurs.

Le mécanisme permettant d'associer le jeton à un appel gRPC dépend du langage et du framework utilisés pour effectuer l'appel. Le mécanisme permettant de spécifier un jeton dans un appel HTTP consiste à inclure un en-tête d'autorisation avec un jeton de support dont la valeur est le jeton, comme indiqué dans les notes d'autorisation pour les cas d'utilisation individuels du suivi des livraisons ou des performances du parc.

L'exemple suivant présente un jeton pour une opération par tâche à partir de votre serveur 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": "*"
       }
    }

L'exemple suivant présente un jeton pour une opération de création de tâches par lot à partir de votre serveur 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": ["*"]
       }
    }

L'exemple suivant montre un jeton pour une opération par véhicule de livraison à partir de votre serveur 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": "*"
       }
    }

L'exemple suivant présente un jeton pour les clients des utilisateurs finaux:

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

L'exemple suivant présente un jeton pour votre application de pilote:

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

Dans le champ kid de l'en-tête, spécifiez l'ID de clé privée de votre compte de service. Vous trouverez cette valeur dans le champ private_key_id du fichier JSON de votre compte de service.
Dans les champs iss et sub, indiquez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champ client_email du fichier JSON de votre compte de service.
Dans le champ aud, spécifiez https://SERVICE_NAME/.
Pour le champ iat, spécifiez l'horodatage de la création du jeton, en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. Prévoyez 10 minutes pour le décalage. Si l'horodatage est trop ancien ou futur, le serveur peut signaler une erreur.
Pour le champ exp, spécifiez l'horodatage de l'expiration du jeton, en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. La valeur recommandée est iat + 3 600.

Lorsque vous signez le jeton à transmettre à un appareil mobile ou à un utilisateur final, veillez à utiliser le fichier d'identifiants pour le rôle de livreur ou de client. Sinon, l'appareil mobile ou l'utilisateur final aura la possibilité de modifier ou d'afficher des informations auxquelles ils ne devraient pas avoir accès.