IoT Central REST API-aanroepen verifiëren en autoriseren

  • Artikel

Met de REST API van IoT Central kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. Gebruik de REST API om te werken met resources in uw IoT Central-toepassing, zoals apparaatsjablonen, apparaten, taken, gebruikers en rollen.

Voor elke Rest API-aanroep van IoT Central is een autorisatieheader vereist die door IoT Central wordt gebruikt om de identiteit van de aanroeper te bepalen en de machtigingen die aanroeper worden verleend in de toepassing.

In dit artikel worden de typen token beschreven die u kunt gebruiken in de autorisatieheader en hoe u deze kunt ophalen. Service-principals zijn de aanbevolen benadering voor toegangsbeheer voor IoT Central REST API.

Tokentypen

Als u toegang wilt krijgen tot een IoT Central-toepassing met behulp van de REST API, kunt u een:

  • Microsoft Entra bearer-token. Een bearer-token is gekoppeld aan een Microsoft Entra-gebruikersaccount of service-principal. Het token verleent de aanroeper dezelfde machtigingen die de gebruiker of service-principal heeft in de IoT Central-toepassing.
  • IoT Central API-token. Een API-token is gekoppeld aan een rol in uw IoT Central-toepassing.

Gebruik een Bearer-token dat is gekoppeld aan uw gebruikersaccount tijdens het ontwikkelen en testen van automatisering en scripts die gebruikmaken van de REST API. Gebruik een bearer-token dat is gekoppeld aan een service-principal voor productieautomatisering en scripts. Gebruik een Bearer-token in voorkeur voor een API-token om het risico op lekken en problemen te verminderen wanneer tokens verlopen.

Zie Gebruikers en rollen beheren in uw IoT Central-toepassing voor meer informatie over gebruikers en rollen in IoT Central.

Een bearer-token ophalen

Gebruik de volgende Azure CLI-opdrachten om een Bearer-token op te halen voor uw Microsoft Entra-gebruikersaccount:

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

Belangrijk

De az login opdracht is nodig, zelfs als u de Cloud Shell gebruikt.

De JSON-uitvoer van de vorige opdracht ziet eruit als in het volgende voorbeeld:

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

Het bearer-token is ongeveer één uur geldig, waarna u een nieuw token moet maken.

Als u een Bearer-token voor een service-principal wilt ophalen, raadpleegt u Verificatie van de service-principal.

Een API-token ophalen

Als u een API-token wilt ophalen, kunt u de IoT Central-gebruikersinterface of een REST API-aanroep gebruiken. Beheer istrators die zijn gekoppeld aan de hoofdorganisatie en gebruikers die zijn toegewezen aan de juiste rol, kunnen API-tokens maken.

Tip

Bewerkingen voor het maken en verwijderen van API-tokens worden vastgelegd in het auditlogboek.

In de IoT Central-gebruikersinterface:

  1. Navigeer naar API-tokens voor machtigingen>.

  2. Selecteer + Nieuw of Maak een API-token.

  3. Voer een naam in voor het token en selecteer een rol en organisatie.

  4. Selecteer Genereren.

  5. IoT Central geeft het token weer dat eruitziet als in het volgende voorbeeld:

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

    Dit scherm is de enige keer dat u het API-token kunt zien als u het kwijtraakt, moet u een nieuw token genereren.

Een API-token is ongeveer één jaar geldig. U kunt tokens genereren voor zowel ingebouwde als aangepaste rollen in uw IoT Central-toepassing. De organisatie die u kiest wanneer u het API-token maakt, bepaalt tot welke apparaten de API toegang heeft. API-tokens die zijn gemaakt voordat u organisaties toevoegt aan uw toepassing, worden gekoppeld aan de hoofdorganisatie.

U kunt API-tokens verwijderen in de gebruikersinterface van IoT Central als u de toegang wilt intrekken.

Met behulp van de REST API:

  1. Gebruik de REST API om een lijst met rol-id's op te halen uit uw toepassing:

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

    Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

    {
  "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. Gebruik de REST API om een API-token voor een rol te maken. Als u bijvoorbeeld een API-token wilt maken dat is aangeroepen operator-token voor de operatorrol:

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

    Aanvraagtekst:

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

    Het antwoord op de vorige opdracht ziet eruit als de volgende JSON:

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

    Dit antwoord is de enige keer dat u toegang hebt tot het API-token, als u dit kwijtraakt, moet u een nieuw token genereren.

U kunt de REST API gebruiken om API-tokens in een toepassing weer te geven en te verwijderen.

Een Bearer-token gebruiken

Als u een Bearer-token wilt gebruiken wanneer u een REST API-aanroep uitvoert, ziet uw autorisatieheader eruit als in het volgende voorbeeld:

Authorization: Bearer eyJ0eX...fNQ

Een API-token gebruiken

Als u een API-token wilt gebruiken wanneer u een REST API-aanroep uitvoert, ziet uw autorisatieheader eruit als in het volgende voorbeeld:

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