Cette section explique les concepts d'authentification et d'autorisation avec concernant l'intégration à Fleet Engine.
Vous pouvez configurer les fonctionnalités fournies par la solution Last Mile Fleet via la console Google Cloud. SDK Fleet Engine nécessitent l'utilisation de jetons Web JSON (JWT) signés par un le service approprié Compte.
Présentation
Les backends clients qui s'authentifient et qui s'autorisent auprès de Fleet Engine doivent utiliser standard Application par défaut Identifiants ces mécanismes.
Fleet Engine reçoit également les appels provenant d'environnements à faible confiance. comme les smartphones et les navigateurs. Pour ne protéger que les clés secrètes de compte de service adapté aux environnements de confiance, l'expérience client les backends doivent générer Jetons Web JSON (JWT) signés avec des revendications supplémentaires spécifiques à Fleet Engine qui peuvent ensuite être envoyés vers des environnements non fiables 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 d'autorisations sur les ressources autorisées pour un compte principal. Par exemple, Les rôles Administrateur sont autorisés à tout faire avec les paramètres par défaut de l'application Certificats, tandis que le rôle de Conducteur non approuvé* ne peut être modifié la position du véhicule et les jetons JWT pour l'authentification une autorisation.
Pour les environnements non approuvés, les revendications JWT limitent davantage les entités auxquelles sur lequel l'appelant peut effectuer une opération. 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 faire un appel sur votre s'exécutant dans un environnement approuvé pour émettre un jeton JWT.
Fleet Engine effectue les contrôles de sécurité suivants sur les appels d'API pour un ressource:
Le compte principal appelant dispose des autorisations appropriées (via le rôle ) pour l'action sur la ressource.
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 le 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 pourrait il peut s'agir de l'application de conduite, de l'application grand public ou d'une application de surveillance.
Le backend du client signe et émet un jeton JWT pour le service correspondant. Google Cloud. L'application cliente reçoit le jeton JWT.
L'application cliente utilise le jeton JWT pour se connecter à Fleet Engine en lecture ou en modification en fonction des rôles IAM qui lui ont été attribués lors de la phase de configuration.
Configuration du projet Cloud
Pour configurer votre projet Cloud, commencez par créer votre projet, puis créer 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, API Local Rides and Deliveries
Comptes de service et Rôles IAM
Un compte de service est un type de compte spécial utilisé par une application, plutôt que par une personne. Un compte de service sert généralement à générer des jetons JWT qui accordent différentes d'autorisations en fonction du rôle. Pour réduire les risques d'abus vous pouvez créer plusieurs comptes de service, chacun disposant d'un ensemble minimal de rôles obligatoire ().
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 véhicules de livraison y compris la mise à jour de l'emplacement du véhicule de livraison et de l'état des tâches ou résultat. Jetons générés par un compte de service doté de ce rôle sont généralement utilisés depuis les appareils mobiles du livreur 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. Jetons frappés par un compte de service doté de ce rôle sont généralement utilisés appareils mobiles du conducteur. |
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 mais pas de mettre à jour les informations sur les tâches. Jetons frappés par un compte de service doté de ce rôle sont généralement utilisés le navigateur Web du client. |
Administrateur Fleet Engine Delivery
roles/fleetengine.deliveryAdmin |
Accorde une autorisation de lecture et d'écriture pour les ressources de diffusion. Comptes principaux disposant de ce rôle n'ont pas besoin d'utiliser de jetons JWT et doivent utiliser à la place Identifiants par défaut. Les revendications JWT personnalisées sont ignorées. Ce rôle doit être limités aux environnements approuvés (backend client). |
roles/fleetengine.deliverySuperUser |
Accorde l'autorisation à toutes les API de tâches et de véhicules de livraison. Jetons frappés par un compte de service doté de ce rôle sont généralement utilisées depuis votre backend serveurs. |
Lecteur Fleet Engine Delivery
roles/fleetengine.deliveryFleetReader |
Accorde l'autorisation de consulter les tâches et véhicules de livraison, et de rechercher à l'aide d'un ID de suivi. Jetons générés par un compte de service avec ce sont généralement utilisés à partir du navigateur Web d'un opérateur de parc de livraison. |
Les organisations qui fournissent à leurs chauffeurs-livreurs des appareils gérés par l'équipe informatique peut tirer parti de la flexibilité offerte par Fleet Engine ; le rôle Utilisateur de conducteurs de confiance et qui choisissent d'intégrer tout ou partie de Fleet Engine interactions dans l'application mobile.
Les organisations acceptant les règles "Bring Your Own Device" doivent opter pour l'option la sécurité du rôle "Conducteur non approuvé Fleet Engine" et ne vous appuyez que l'application mobile pour envoyer des mises à jour de la position des véhicules à Fleet Engine. Toutes les autres 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 grand public affichent des messages d'erreur lorsqu'un autorisation requise manquante. Par conséquent, nous vous recommandons vivement en utilisant l'ensemble standard de rôles présenté ci-dessus au lieu des rôles personnalisés.
Créer un compte de service
Vous pouvez créer un compte de service à l'aide de la IAM & Admin > Service Accounts
de la console Google Cloud. Dans la liste déroulante Rôle, sélectionnez
Fleet Engine et attribuer l'un des rôles au compte de service. C'est bon
c'est-à-dire 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 fiables, en ajoutant le rôle Créateur de jetons du compte de service permet aux utilisateurs 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
vous authentifier avec gcloud (gcloud auth list
--format='value(account)'
).
Bibliothèque d'authentification Fleet Engine
Fleet Engine utilise des jetons JWT pour restreindre l'accès aux API Fleet Engine de l'infrastructure. La bibliothèque d'authentification Fleet Engine, disponible sur GitHub, simplifie de créer des jetons JWT Fleet Engine et de les signer 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 (tels que 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 directement dans votre codebase. Pour cela, vous devez avoir à la fois sur les jetons JWT et sur leur lien avec Fleet Engine. C'est pourquoi nous 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 s'assurer que les appareils ne peuvent modifier les véhicules ou les tâches que pour qu'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 le (obtenue auprès des comptes de service) et le chiffrement algorithme. La section "Revendication" contient des informations telles que le la date de création, la valeur TTL (Time To Live) du jeton, les services auxquels il est Revendiquer l'accès et d'autres informations d'autorisation pour réduire le champ d'application l'accès aux données ; (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. 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 le le code temporel est trop éloigné dans le passé ou dans le futur, le serveur risque de signaler une erreur. |
exp |
Code temporel 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 le code temporel est plus d’une heure dans le futur. |
authorization |
Selon le cas d'utilisation, peut contenir "deliveryvehicleid", "trackingid", "taskid" ou "taskids". |
La génération d'un jeton JWT fait référence à sa signature. Instructions et exemples de code pour créer et signer le jeton JWT, consultez Autorisation via un 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 permet de s'assurer
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 la livraison par ce livreur.
identifiant du véhicule. Ensuite, selon le rôle du pilote, les jetons n'autorisent l'accès
l'ID spécifique du véhicule à diffuser, et non tout autre ID arbitraire du véhicule.
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 deBatchCreateTasksAPI
. Cette revendication doit être sous forme de tableau. Le tableau doit contenir tous les ID de tâche nécessaires pour terminer la demande. N'incluez pasdelivervehicleid
,trackingid
nitaskid
revendications.trackingid
: à utiliser lors de l'appel deGetTaskTrackingInfoAPI
. La revendication doit correspondent à l'ID de suivi de la demande. N'incluez pasdelivervehicleid
, des revendicationstaskid
outaskids
.
Le jeton doit également contenir la revendication appropriée lorsque vous appelez des API.
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
dans le tableau.
Si vous souhaitez créer et signer un fichier JSON directement en tant que porteur de jetons, plutôt que à l'aide de jetons d'accès OAuth 2.0, lisez les instructions Autorisation via un 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 le framework utilisé pour passer l'appel. Mécanisme permettant de spécifier un jeton à 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 clés suivi des expéditions ou les performances du parc différents cas d'utilisation.
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 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'adresse IP privée de votre compte de service ID de clé. Vous trouverez cette valeur dans le champprivate_key_id
de votre fichier JSON du compte de service. - Dans les champs
iss
etsub
, indiquez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champclient_email
de votre compte de service JSON. - Pour le champ
aud
, indiquez https://SERVICE_NAME/. - Pour le champ
iat
, spécifiez le code temporel correspondant à 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 le code temporel est trop éloigné dans le passé, ou dans le futur, le peut signaler une erreur. - Pour le champ
exp
, spécifiez le code temporel d'expiration du jeton. en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. La valeur recommandée estiat
+ 3 600.
Lorsque vous signez le jeton à transmettre à un appareil mobile ou à un utilisateur final, assurez-vous pour utiliser le fichier d'identifiants pour le rôle Conducteur de livraison ou Consommateur. Sinon, l'appareil mobile ou l'utilisateur final ont la possibilité de modifier ou d'afficher des informations auxquelles ils ne devraient pas avoir accès.