Introduction
Objectif du DAP
L’objectif du Device Access Proxy (DAP) est de sécuriser les communications entre les équipements ou services tiers et IO-base.
Le système s’appuie sur la distribution de tokens d’authentification permettant de s’assurer que seuls les équipements préalablement approuvés, et donc considérés comme fiables, peuvent communiquer avec Io-base.
Les comptes de service
Lors de la demande de tokens, l’équipement (ou service) va utiliser un compte de service (voir section 3 : Validation de l’équipement dans le portail de Io-base).
Il existe un compte de service générique “default”, qui devrait de préférence être utilisé pour les tests.
Avant d’entamer la procédure, il est recommandé de demander un compte de service dédié à l’utilisation de l’équipement (ou service) pour avoir une meilleure maîtrise des droits d’accès sur Io-base.
Pour effectuer une demande de compte de service DAP, contactez le support en précisant :
le nom du compte de service
les droits nécessaires : read, write ou read/write
Ainsi, si besoin, il sera possible de restreindre les droits aux seules métriques nécessaires.
1 : Accès à l’interface de requêtes de l’API
Pour accéder à l'interface de requêtes de l'API, se connecter à Io-base et cliquer sur le bouton en forme de roue crantée en haut à droite de l'écran :
La page d'administration de Io-base s'ouvre.
Aller au menu Autres/Console API :
Ensuite, sélectionnez l'API Device Authentication Proxy, à l’aide de la liste déroulante en haut à gauche de l’écran.
Cliquez ensuite sur le bouton Authorize, à droite de l’écran.
Saisissez la clé API demandée (contactez votre administrateur si vous ne l’avez pas), puis cliquez sur Authorize.
Vous pouvez maintenant fermer la fenêtre en cliquant sur Close.
2 : Enregistrement de l’équipement
Vous allez maintenant pouvoir effectuer l’enregistrement du nouvel équipement.
Pour ce faire, allez à la section Device Registration, puis cliquez sur la rubrique POST / register.
Cliquez ensuite sur le bouton “Try it out”.
L’écran ci-dessous apparaît :
Complétez la requête en renseignant un nom pour identifier votre appareil, dans notre exemple, on l'appellera “device_documentation”.
Puis cliquez sur Execute.
Une réponse avec un Code 200 apparaît : l’équipement a été enregistré avec succès.
Dans le corps de cette réponse, conservez le paramètre “device_code”, il vous sera utile lors de la récupération du token d’accès (voir section 4 : Récupération du token d’accès).
Remarque : Si un équipement portant ce nom a déjà été enregistré, l’enregistrement n’est pas possible et vous aurez une réponse avec un code 403 :
3 : Validation de l’équipement dans le portail de Io-base
Cette action doit être effectuée par un administrateur.
Votre équipement est enregistré. Il va maintenant devoir être validé par un utilisateur ayant un rôle d’administrateur fonctionnel.
Voici la démarche à suivre pour l’administrateur :
Pour y accéder, se connecter à Io-base et cliquer sur le bouton en forme de roue crantée en haut à droite de l'écran :
La page d'administration de Io-base s'ouvre.
Aller au menu "Services et équipements" :
Vous êtes redirigés vers l'écran de gestion des équipements.
On voit que notre équipement “device_documentation” est en Attente de validation.
Dans la colonne Actions, cliquez sur le bouton Valider l'équipement.
Une fenêtre s'ouvre. Dans la liste déroulante, choisissez le compte de service que vous souhaitez associer à l'équipement.
Ensuite, cliquez sur Valider.
Remarque : Il est préférable ici d’utiliser un compte de service dédié à l’équipement plutôt que le compte de service par défaut (voir Introduction).
L'équipement est maintenant validé.
Pour plus d’informations sur le portail des équipements, consultez notre documentation sur la gestion des équipements dans Io-base.
4 : Récupération du token d’accès
Une fois que votre équipement a été enregistré et validé par un administrateur, il va pouvoir récupérer un token d’accès, qui vous permet d'appeler les API Indaba.
Ce token a une durée de validité donc une fois expiré, il faut en demander un autre (voir section 5 : Rafraîchissement du token).
Suivez la procédure suivante pour récupérer un token d’accès :
Accéder à nouveau à l’interface de requêtes de l'API (voir section 1: Accès à l’interface de requêtes de l’API).
Aller à la section Token management, puis cliquer sur la rubrique Post / Token.
Compléter la requête en saisissant :
le device_code : il s’agit du code envoyé dans le corps de la réponse reçue suite à votre requête d’enregistrement de l’équipement (voir section 2 : Enregistrement de l’équipement)
le client_id : il s’agit du nom que vous avez indiqué lors de l’enregistrement de votre équipement, dans notre exemple “device_documentation”
Cliquez ensuite sur Execute :
La réponse suivante apparaît :
Dans le corps de cette réponse, vous allez retrouver :
l’access_token, qui permet d’appeler les API Indaba :
le refresh token, il va vous servir à renouveler l’accès à Io-base lorsque la validité du token d’accès aura expiré.
Remarque : dans le portail des équipements de Io-base, l’état de l’équipement passe en “Token récupéré”.
Attention, pour des raisons de sécurité, l’appel à token n’est valide qu’une seule fois !
En cas d’appel à token après récupération, l’équipement se met en erreur.
Dans ce cas, l'équipement doit être supprimé par un administrateur dans Io-base, et il faut recommencer la procédure.
Remarque : Si l’équipement n’a pas encore été validé par un administrateur, le token d’accès ne pourra pas être récupéré.
On aura une réponse avec un code 425 : “Authorization Pending”.
Assurez-vous que l’équipement soit validé puis effectuez l’opération à nouveau.
5 : Rafraîchissement du token
Le token d’accès attribué à l’équipement a une durée de validité limitée. Ainsi, pour continuer à communiquer avec Io-base, il va falloir renouveler ce token.
Pour ce faire, retournez à l’interface de requête API (voir section 1 : Accès à l’interface de requêtes de l’API).
Dans la section Token Management, cliquez sur la rubrique Post/refresh.
Puis, Try it out.
On arrive sur l’écran suivant :
Compléter la requête en saisissant :
le “refresh_token” : que vous trouverez dans le corps de la réponse d’attribution du token précédent. Dans notre cas, ici :
le “client_id” : le nom que vous avez saisi lors de l’enregistrement de l’équipement, dans notre cas “device_documentation” (voir section 2 : Enregistrement de l’équipement)
On aura donc :
Cliquez ensuite sur Execute.
Le token a bien été rafraîchi et la communication entre l’équipement et Io-base est assurée (réponse avec un code 200) :
Dans le corps de la réponse, vous allez trouver :
l’access_token, qui permet d’appeler les API Indaba :
le refresh token, qui vous servira à renouveler la communication entre l’équipement et Io-base lorsque ce nouveau token sera expiré à son tour.
Attention, un “refresh_token” ne peut être utilisé qu’une seule fois !
Si le même token est utilisé deux fois, l’équipement se met en erreur.
Dans ce cas, l'équipement doit être supprimé par un administrateur dans Io-base, et il faut recommencer la procédure.