Comment authentifier et autoriser les appels d’API REST IoT Central

Article
03/09/2024

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Utilisez l’API REST pour utiliser les ressources de votre application IoT Central, telles que les modèles d’appareils, les appareils, les travaux, les utilisateurs et les rôles.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation dont se sert IoT Central pour déterminer l’identité de l’appelant et les autorisations qui lui ont été accordées dans l’application.

Cet article décrit les types de jetons que vous pouvez utiliser dans l’en-tête d’autorisation et la façon de les obtenir. Les principaux de service constituent l’approche recommandée pour la gestion de l’accès à l’API REST IoT Central.

Types de jetons

Pour accéder à une application IoT Central à l’aide de l’API REST, vous pouvez utiliser :

Jeton du porteur Microsoft Entra. Un jeton du porteur est associé à un compte d’utilisateur ou un principal de service Microsoft Entra. Le jeton accorde à l’appelant les mêmes autorisations que celles dont l’utilisateur ou le principal de service dispose dans l’application IoT Central.
Un jeton d’API IoT Central. Un jeton d’API est associé à un rôle dans votre application IoT Central.

Utilisez un jeton du porteur associé à votre compte d’utilisateur pendant que vous développez et testez l’automatisation et les scripts qui utilisent l’API REST. Utilisez un jeton du porteur associé à un principal de service pour l’automatisation de production et les scripts. Utilisez un jeton du porteur de préférence à un jeton d’API afin de réduire le risque de fuites et de problèmes lors de l’expiration des jetons.

Pour plus d’informations sur les utilisateurs et les rôles dans IoT Central, consultez Gérer les utilisateurs et rôles dans votre application IOT Central.

Obtenir un jeton du porteur

Pour obtenir un jeton du porteur pour votre compte d’utilisateur Microsoft Entra, utilisez les commandes Azure CLI suivantes :

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Important

La commande az login est nécessaire même si vous utilisez Cloud Shell.

La sortie JSON de la commande précédente ressemble à l’exemple suivant :

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

Le jeton du porteur est valide pendant environ une heure. Après quoi, vous devez en créer un nouveau.

Pour obtenir un jeton du porteur pour un principal du service, consultez Authentification du principal du service.

Obtenir un jeton d’API

Pour obtenir un jeton d’API, vous pouvez utiliser l’interface utilisateur IoT Central ou un appel d’API REST. Les administrateurs associés à l’organisation racine et les utilisateurs affectés au rôle correct peuvent créer des jetons d’API.

Conseil

Les opérations de création et de suppression sur les jetons d’API sont enregistrées dans le journal d’audit.

Dans l’interface utilisateur IoT Central :

Accédez à Autorisations > Jetons d’API.
Sélectionnez + Nouveau ou Créer un jeton d’API.
Entrez un nom pour le jeton et sélectionnez un rôle et une organisation.
Sélectionnez Générer.
IoT Central affiche le jeton qui ressemble à l’exemple suivant :

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

C’est la seule fois que le jeton d’API s’affiche à l’écran. Si vous le perdez, vous devez en générer un nouveau.

Un jeton d’API est valide pendant environ un an. Vous pouvez en générer pour les rôles intégrés et personnalisés dans votre application IoT Central. L’organisation que vous choisissez lors de la création du jeton d’API détermine à quels appareils l’API a accès. Tous les jetons d’API créés avant l’ajout d’organisations à votre application sont associés à l’organisation racine.

Si vous avez besoin de révoquer un accès, vous pouvez supprimer des jetons d’API dans l’interface utilisateur IoT Central.

Utilisation de l’API REST :

Utilisez l’API REST pour récupérer la liste d’ID de rôle de votre application :

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

Utilisez l’API REST pour créer un jeton d’API pour un rôle. Par exemple, pour créer un jeton d’API appelé operator-token pour le rôle d’opérateur :

PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=2022-07-31

Corps de la demande :

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

La réponse à la commande précédente ressemble à la sortie JSON suivante :

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

Cette réponse est le seul moment où vous avez accès au jeton d’API. Si vous le perdez, vous devez en générer un nouveau.

Vous pouvez utiliser l’API REST pour lister et supprimer les jetons d’API d’une application.

Utiliser un jeton du porteur

Pour utiliser un jeton du porteur au moment d’effectuer un appel d’API REST, votre en-tête d’autorisation ressemble à l’exemple suivant :

Authorization: Bearer eyJ0eX...fNQ

Utiliser un jeton d’API

Pour utiliser un jeton d’API au moment d’effectuer un appel d’API REST, votre en-tête d’autorisation ressemble à l’exemple suivant :

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

Partager via