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 décrit les concepts d'authentification et d'autorisation liés à l'intégration à Fleet Engine.

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

Présentation

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

Fleet Engine reçoit également des appels provenant d'environnements à faible confiance tels que des smartphones et des navigateurs. Pour protéger les clés secrètes de compte de service uniquement adaptées aux environnements approuvés, 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 émis vers des environnements non approuvés tels que les 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 Administrateur sont autorisés à tout faire avec les identifiants par défaut de l'application, tandis que le rôle Conducteur non approuvé* ne permet que de mettre à jour la position du véhicule et est limité à l'utilisation de 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.
Votre code exécuté dans un environnement à faible confiance doit d'abord appeler votre 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 à une ressource:
1. Le compte principal appelant dispose des autorisations appropriées (via l'attribution de rôle) pour l'action sur la ressource.
2. Pour les rôles autres que ceux d'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 ces détails de flux d'authentification.

L'administrateur du parc crée des comptes de service.
L'administrateur de parc attribue des rôles IAM spécifiques aux comptes de service.
L'administrateur de 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 client. Le demandeur peut être l'application du pilote, l'application du consommateur ou une application de surveillance.
Le backend du 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 les données, en fonction des rôles IAM qui lui sont attribués lors de la phase de configuration.

Schéma de la séquence d'authentification

Configuration du 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:

Créez un projet Google Cloud à l'aide de la console Google Cloud.
À l'aide du tableau de bord des API et 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 sert à générer des jetons JWT qui accordent différents ensembles d'autorisations en fonction du rôle. Pour réduire les risques d'utilisation abusive, vous pouvez créer plusieurs comptes de service, chacun disposant de l'ensemble minimal de rôles requis ().

La solution Last Mile Fleet utilise les rôles suivants:

Rôle	Description
Utilisateur de confiance Fleet Engine Delivery `roles/fleetengine.deliveryTrustedDriver`	Accorde l'autorisation de créer et de mettre à jour les tâches et les véhicules de livraison, y compris l'emplacement du véhicule et l'état ou le résultat de la tâche. 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 du livreur ou de vos serveurs backend.
Utilisateur non approuvé Fleet Engine Delivery `roles/fleetengine.deliveryUntrustedDriver`	Accorde l'autorisation de mettre à jour la position du véhicule 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 des appareils mobiles du livreur.
Consommateur Fleet Engine Delivery `roles/fleetengine.deliveryConsumer`	Accorde l'autorisation de rechercher des tâches à l'aide d'un ID de suivi et de lire les informations les concernant, 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 du client du service de livraison.
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 et doivent 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 de 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`	Accorde l'autorisation de consulter 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 parc de livraison.

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

Les organisations qui appliquent les règles Bring Your Own Device doivent opter pour la sécurité du rôle "Conducteur non approuvé Fleet Engine" et n'utiliser que l'application mobile pour envoyer des mises à jour de la position des véhicules à Fleet Engine. Toutes les autres interactions doivent provenir des serveurs backend du client.

Les SDK Driver et Consumer SDK s'appuient sur ces rôles standards. Toutefois, il est possible de créer des rôles personnalisés qui permettent de regrouper un ensemble arbitraire d'autorisations. Le pilote et le SDK client affichent des messages d'erreur lorsqu'une autorisation requise est manquante. Par conséquent, nous vous recommandons vivement d'utiliser l'ensemble standard de rôles présenté ci-dessus plutôt que des 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, ajouter des 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 auprès de gcloud (gcloud auth list --format='value(account)').

Bibliothèque d'authentification Fleet Engine

Fleet Engine utilise des jetons JWT pour limiter l'accès aux API Fleet Engine dans les 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.

Cette bibliothèque offre les avantages suivants:

Simplifie le processus de création des jetons Fleet Engine.
Fournit des mécanismes de signature de jetons autres que l'utilisation de fichiers d'identifiants (par exemple, en empruntant l'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 avoir une connaissance approfondie des jetons JWT et de leur relation avec Fleet Engine. C'est pourquoi nous vous recommandons vivement d'utiliser la bibliothèque Auth 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 à partir des comptes de service) et l'algorithme de chiffrement. La section de revendication contient des informations telles que la date de création du jeton, sa valeur TTL, les services auxquels le jeton revendique l'accès et d'autres informations d'autorisation permettant de réduire le champ d'application de 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".
`kid`	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é d'un compte de service disposant du niveau d'autorisation approprié.

Une section de revendications JWT contient les champs suivants:

Champ	Description
`iss`	Adresse e-mail de votre compte de service.
`sub`	Adresse e-mail de votre compte de service.
`aud`	SERVICE_NAME de votre compte de service, dans ce cas https://fleetengine.googleapis.com/
`iat`	Code temporel de la création du jeton, spécifié en secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC. Le décalage peut prendre 10 minutes. Si l'horodatage est trop ancien ou trop éloigné dans le futur, le serveur peut signaler une erreur.
`exp`	Horodatage de l'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 éloigné de plus d'une heure.
`authorization`	Peut contenir "deliveryvehicleid", "trackingid", "taskid" ou "taskids".

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

Revendications JWT

La solution Last Mile Fleet 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 du conducteur, les jetons n'autorisent l'accès qu'à l'ID du véhicule de diffusion spécifique, et non à tout autre ID de véhicule arbitraire.

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

deliveryvehicleid : à utiliser lors de l'appel des API par livraison-véhicule.
taskid : à utiliser lors de l'appel d'API par tâche.
taskids : à utiliser lors de l'appel de BatchCreateTasksAPI. Cette revendication doit se présenter sous forme de tableau, et le tableau doit contenir tous les ID de tâche nécessaires pour exécuter 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 porteur de jetons, plutôt que d'utiliser des jetons d'accès OAuth 2.0, lisez les instructions concernant l'autorisation de compte de service sans OAuth dans la documentation Identity Developer.

Le mécanisme d'association du 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 pour un appel HTTP consiste à inclure un en-tête "Authorization" avec un jeton de support dont la valeur est le jeton, comme indiqué dans les notes d'autorisation pour les cas d'utilisation individuels de suivi des expéditions ou de performances du parc.

L'exemple suivant montre 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 montre 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 présente un jeton associé à 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 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 montre 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.
Pour le champ aud, indiquez https://SERVICE_NAME/.
Pour le champ iat, spécifiez l'horodatage de la création du jeton, exprimé 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 trop éloigné dans le futur, le serveur peut signaler une erreur.
Pour le champ exp, spécifiez le code temporel d'expiration du jeton, exprimé 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 Conducteur de livraison ou Consommateur. Sinon, l'appareil mobile ou l'utilisateur final pourra modifier ou afficher des informations auxquelles il ne devrait pas avoir accès.