Gérer les clés d’API

Les clés d’API permettent :

- Aux équipements utilisant MQTT de se connecter à la plateforme

- Aux applications métiers d’utiliser les services Live Objects via les API (MQTT et REST) : o Exploration de données (Search)

o Consommation de données en temps réel o Device management

o Configuration (utilisateurs, décodeurs etc.)

Toutes les fonctionnalités disponibles via le portail Live Objects le sont également via les API REST (voir https://liveobjects.orange-business.com/#/swagger)

Les API MQTT sont réservées :

- à la connexion des équipements utilisant ce protocole

- à la consommation de données en temps réel par les applications métier

Comme pour les utilisateurs il est possible d’affecter des rôles à des clés d’API, afin d’autoriser certains fonctionnalités. Par exemple :

- une clé API utilisée par un équipement MQTT ne nécessite que le rôle DEVICE_ACCESS - une application métier qui a besoin d’utiliser les API de « device management »

nécessitera le rôle DEVICE_R (si consultation simple) et DEVICE_R + DEVICE_W (si consultation et modification)

- une application métier qui a besoin de consommer des données en temps réel via MQTT aura besoin du rôle BUS_R

NB : pour chaque API REST, le rôle nécessaire est indiqué dans le swagger (https://liveobjects.orange-business.com/#/swagger).

Pour visualiser l’ensemble des clés d’API crées dans votre compte Live Objects allez dans la rubrique « Clés d’API » du menu « Configuration ».

2.6.6.1. Créer une clé d’API

Pour créer une nouvelle clé d’API cliquer sur le bouton « Ajouter » du menu principal.

Lors de la création d’une clé d’API vous pouvez choisir de lui affecter un profil de droits prédéfini en fonction de votre usage, ou un profil personnalisé.

- Le profil « Equipement MQTT » est le profil à sélectionner pour les clés destinées à connecter des équipements MQTT.

- Le profil « Application » est le profil à sélectionner pour les clés utilisées par les serveurs applicatifs pour les usages principaux : consommation de données en temps réel, configuration de files de message, gestion des décodeurs et « Event processing ».

- Le profil « Connecteur externe » est le profil à sélectionner pour les clés destinées à être utilisées par des connecteurs externes. Un connecteur externe permet de gérer dans Live Objects des équipements « cloud » ne pouvant pas être connectés directement à Live Objects (connectivité, modèle de donnée ou mode de fonctionnement propriétaires ou non supportés par Live Objects)

- Pour des besoins plus avancés (« Device management », gestion de campagne par exemple), utiliser le profil « Personnalisé » et sélectionnez les droits souhaités.

Vous pouvez également définir une période de validité pour votre clé. A l’expiration de la période la clé sera automatiquement désactivée.

Il est également possible de restreindre une clé d’API à une ou plusieurs files de messages (fifo).

Cela signifie que cette clé ne pourra être utilisée que pour la consommation des messages routés dans les files spécifiées et uniquement cela. La consommation de messages sur d’autres files, ou l’utilisation d’autres API, notamment REST, avec cette clé sera impossible.

Cette fonctionnalité vous permet de partager avec un tiers des données issues de certains

Remarque importante : La clé n’est pas stockée dans Live Objects. Seul un hash est conservé dans la plateforme. Il vous appartient de la conserver en lieu sûr. En cas de perte la clé ne pourra être retrouvée dans Live Objects, elle devra être supprimée et régénérée et les systèmes l’utilisant (équipements MQTT, applications) devront être mis à jour avec la nouvelle clé.

2.6.6.2. Hiérarchie des clés d’API

Il est possible de créer des clés filles d’une clé d’API. Ces clés filles hériteront automatiquement des rôles de la clé parent ainsi que de sa validité.

Il n’est pas possible d’ajouter à une fille des rôles non détenus par la clé parent.

La désactivation de la clé parent, entraine automatiquement la désactivation de toute sa descendance.

L’utilisation de clés filles peut être utile pour gérer des groupes et sous-groupes de clés d’API.

Par exemple une seule clé d’API pour un groupe d’équipements, avec une clé fille pour chacun, permettra de désactiver en un clic l’accès à Live Objects pour ce groupe d’équipements.

Pour créer une clé fille, il suffit de sélectionner la clé désirée en cliquant dessus dans la liste, puis de cliquer sur le bouton « Ajouter » dans l’écran de modification, en bas de page.

2.6.6.3. Régénérer une clé d’API

Vous pouvez régénérer une clé à partir de l’écran de modification de la clé, en cliquant sur le bouton « Régénérer ». Une nouvelle valeur de clé sera alors générée et l’ancienne valeur sera caduque. Si vous régénérez une clé (en cas de perte, par exemple) vous devez mettre à jour les systèmes qui l’utilisent (équipements MQTT, applications).

2.6.6.4. Désactiver/ réactiver une clé d’API

Vous pouvez avoir besoin de désactiver temporairement une clé d’API. Cela est possible à partir de l’écran de modification de la clé, en cliquant sur le bouton « Désactiver ». L’accès API deviendra alors impossible pour tout système utilisant cette clé. Inversement, une clé peut être instantanément réactivée en cliquant sur le bouton « Activer » présent dans l’écran de modification de la clé, ou via la liste principale en cliquant sur l’icône « Activer »

2.6.6.5. Supprimer une clé d’API

Pour supprimer une ou plusieurs clés d’API, sélectionnez-les dans la liste principale et cliquez sur l’icône « Supprimer ».

La suppression est irréversible, et l’accès à tout système utilisant la ou les clés est rendu impossible.

NB : La suppression d’une clé parent entraine automatiquement la suppression de toutes ses clés filles.

2.6.6.6. Passer une clé d’API en mode debug

Le passage en mode debug d’une clé d’API permet l’affichage dans le journal d’activité des

Lorsque le mode debug est activé, cela est mentionné dans les détails de la clé ainsi que le temps restant.

2.6.6.7. Associer une autorité de certification

Vous pouvez authentifier vos équipements, ou applications utilisant une clé d’API pour se connecter à Live Objects en utilisant vos propres certificats. C’est le principe d’authentification

mutuelle (SSL-two ways

https://liveobjects.orange-business.com/doc/html/lo_manual_v2.html#_go_further_and_use_2_way_authentication).

Outre le renforcement de la sécurité cette fonctionnalité apporte plus de souplesse dans la gestion des flottes d’équipements MQTT, puisqu’elle permet de construire les firmware des équipements avec une seule et même clé d’API. L’authentification se faisant sur la base du certificat de l’équipement.

Pour cela il faut d’abord importer dans Live Objects les certificats des autorités de certification utilisées pour signer les certificats clients des applications ou équipements que vous voulez authentifier. Pour cela rendez-vous dans le menu « Configuration>Clés d’API ». Dans l’onglet

« Certificat CA » cliquez sur le bouton « importer un certificat CA »

Ensuite vous pourrez associer cette autorité de certification à une clé d’API. Voir le paragraphe

« Créer une clé d’API »

NB : En cas de suppression dans Live Objects du certificat de votre autorité de certification, les clés d’API associées deviendront inopérantes. Il faudra alors désactiver l’option « authentification forte ». Voir le paragraphe « Créer une clé d’API »