Wie Sie IoT Central-REST-API-Aufrufe authentifizieren und autorisieren

  • Artikel

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Verwenden Sie die REST-API, um mit Ressourcen in Ihrer IoT Central-Anwendung zu arbeiten, z. B. Gerätevorlagen, Geräte, Aufträge, Benutzer und Rollen.

Jeder IoT Central REST-API-Aufruf erfordert einen Autorisierungsheader, der IoT Central verwendet, um die Identität des Aufrufers und die Berechtigungen zu bestimmen, die dem Aufrufer innerhalb der Anwendung erteilt werden.

In diesem Artikel werden die Tokentypen beschrieben, die Sie im Autorisierungsheader verwenden können, und es wird erklärt, wie Sie sie abrufen. Dienstprinzipale sind der empfohlene Ansatz für die IoT Central REST-API-Zugriffsverwaltung.

Tokentypen

Um mithilfe IoT Central REST-API auf eine Anwendung zuzugreifen, können Sie eine der folgenden Funktionen verwenden:

  • Microsoft Entra Bearertoken. Ein Bearertoken ist einem Microsoft Entra-Benutzerkonto oder Dienstprinzipal zugeordnet. Das Token gewährt dem Aufrufer die gleichen Berechtigungen wie dem Benutzer oder Dienstprinzipal in der IoT Central-Anwendung.
  • IoT Central-API-Token. Ein API-Token ist einer Rolle in Ihrer IoT Central-Anwendung zugeordnet.

Verwenden Sie ein Ihrem Benutzerkonto zugeordnetes Bearertoken, während Sie Automatisierung und Skripts entwickeln und testen, die die REST-API nutzen. Verwenden Sie für die Produktionsautomatisierung und Skripte ein Bearertoken, das mit einem Dienstprinzipal verbunden ist. Ziehen Sie ein Bearertoken einem API-Token vor, um das Risiko von Verlusten und Problemen beim Ablauf von Token zu verringern.

Weitere Informationen zu Benutzern und Rollen in IoT Central finden Sie unter Verwalten von Benutzern und Rollen in Ihrer IoT Central Anwendung.

Abrufen eines Bearertokens

Verwenden Sie die folgenden Azure CLI-Befehle, um ein Bearertoken für Ihr Microsoft Entra-Benutzerkonto abzurufen:

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

Wichtig

Der az login-Befehl ist auch dann erforderlich, wenn Sie die Cloud Shell benutzen.

Die JSON-Ausgabe des vorherigen Befehls sieht wie im folgenden Beispiel aus:

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

Das Bearertoken ist ungefähr eine Stunde lang gültig, dann müssen Sie ein neues erstellen.

Informationen zum Abrufen eines Bearertokens für einen Dienstprinzipal finden Sie unter Dienstprinzipalauthentifizierung.

Abrufen eines API-Tokens

Um ein API-Token abzurufen, können Sie die IoT Central-Benutzeroberfläche oder einen REST-API-Aufruf verwenden. Administratoren, die der Stammorganisation zugeordnet wurden, und Benutzer, die der richtigen Rolle zugewiesen wurden, können API-Token erstellen.

Tipp

Erstellungs- und Löschvorgänge auf API-Token werden im Überwachungsprotokoll aufgezeichnet.

Auf der IoT Central-Benutzeroberfläche:

  1. Navigieren Sie zu Berechtigungen > API-Token.

  2. Wählen Sie + Neu oder API-Token erstellen.

  3. Geben Sie einen Namen für das Token ein, und wählen Sie eine Rolle und Organisation aus.

  4. Wählen Sie Generieren aus.

  5. IoT Central zeigt das Token an, das wie im folgenden Beispiel aussieht:

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

    Dieser Bildschirm ist das einzige Mal, dass Sie das API-Token sehen können. Wenn Sie es verlieren, müssen Sie ein neues generieren.

Ein API-Token ist ungefähr ein Jahr lang gültig. Sie können Token sowohl für integrierte als auch für benutzerdefinierte Rollen in Ihrer IoT Central-Anwendung generieren. Die Organisation, die Sie beim Erstellen des API-Tokens auswählen, bestimmt, auf welche Geräte die API zugreifen kann. Alle API-Token, die erstellt werden, bevor Sie Ihrer Anwendung Organisationen hinzufügen, werden der Stammorganisation zugeordnet.

Sie können API-Token auf der IoT Central Benutzeroberfläche löschen, wenn Sie den Zugriff widerrufen müssen.

Mithilfe der REST API:

  1. Verwenden Sie die REST-API, um eine Liste der Rollen-IDs aus Ihrer Anwendung abzurufen:

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

    Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

    {
  "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"
    }
  ]
}

  2. Verwenden Sie die REST-API, um ein API-Token für eine Rolle zu erstellen. So erstellen Sie beispielsweise ein API-Token namens operator-token für die Operatorrolle:

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

    Anforderungstext:

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

    Die Antwort auf den vorherigen Befehl sieht wie folgt aus:

    {
  "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"
}

    Diese Antwort ist die einzige Zeit, in der Sie Zugriff auf das API-Token haben, wenn Sie es verlieren, müssen Sie ein neues generieren.

Sie können die REST-API verwenden, um API-Token in einer Anwendung aufzulisten und zu löschen.

Abrufen eines Bearertokens

Um ein Bearertoken zu verwenden, wenn Sie einen REST-API-Aufruf ausführen, sieht Ihr Autorisierungsheader wie im folgenden Beispiel aus:

Authorization: Bearer eyJ0eX...fNQ

Verwendung eines API-Tokens

Um ein Bearertoken zu verwenden, wenn Sie einen REST-API-Aufruf ausführen, sieht Ihr Autorisierungsheader wie im folgenden Beispiel aus:

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