Toegang tot Azure IoT Hub Device Provisioning Service (DPS) beheren met handtekeningen voor gedeelde toegang en beveiligingstokens

In dit artikel worden de beschikbare opties beschreven voor het beveiligen van uw Azure IoT Hub Device Provisioning Service (DPS). De inrichtingsservice maakt gebruik van verificatie en machtigingen om toegang te verlenen tot elk eindpunt. Met machtigingen kan het verificatieproces de toegang tot een service-exemplaar beperken op basis van functionaliteit.

In dit artikel wordt het volgende besproken:

• Het verificatieproces en de tokens die door de inrichtingsservice worden gebruikt om machtigingen te verifiëren voor zowel de Service- als Device REST API's.

• De verschillende machtigingen die u aan een back-end-app kunt verlenen voor toegang tot de Service-API.

Verificatie

De Apparaat-API ondersteunt apparaatverificatie op basis van sleutels en X.509-certificaten.

De Service-API ondersteunt verificatie op basis van sleutels voor back-end-apps.

Bij het gebruik van verificatie op basis van sleutels gebruikt Device Provisioning Service beveiligingstokens om services te verifiëren om te voorkomen dat sleutels op de kabel worden verzonden. Bovendien zijn beveiligingstokens beperkt in de geldigheid en het bereik van de tijd. Azure IoT Device Provisioning SDK's genereren automatisch tokens zonder speciale configuratie.

In sommige gevallen moet u mogelijk de REST API's van DE HTTP Device Provisioning Service rechtstreeks gebruiken zonder de SDK's te gebruiken. In de volgende secties wordt beschreven hoe u rechtstreeks verifieert met de REST API's.

Apparaat-API-verificatie

De Apparaat-API wordt door apparaten gebruikt om de Device Provisioning Service te attesteren en een IoT Hub-verbinding te ontvangen.

Notitie

Als u een geverifieerde verbinding wilt ontvangen, moeten apparaten eerst worden geregistreerd in Device Provisioning Service via een inschrijving. Gebruik de Service-API om programmatisch een apparaat te registreren via een inschrijving.

Een apparaat moet worden geverifieerd bij de Apparaat-API als onderdeel van het inrichtingsproces. De methode die een apparaat gebruikt om te verifiëren, wordt gedefinieerd wanneer u een inschrijvingsgroep of afzonderlijke inschrijving instelt. Wat de verificatiemethode ook is, het apparaat moet een HTTPS PUT uitgeven aan de volgende URL om zichzelf in te richten.

    https://global.azure-devices-provisioning.net/[ID_Scope]/registrations/[registration_id]/register?api-version=2021-06-01

Als u verificatie op basis van sleutels gebruikt, wordt een beveiligingstoken doorgegeven in de header van de HTTP-autorisatieaanvraag in de volgende indeling:

    SharedAccessSignature sig={signature}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI} 

Structuur van beveiligingstokens voor verificatie op basis van sleutels

Het beveiligingstoken wordt doorgegeven in de header van de HTTP-autorisatieaanvraag in de volgende indeling:

    SharedAccessSignature sig={signature}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI} 

De verwachte waarden zijn:

Waarde	Omschrijving
{signature}	Een HMAC-SHA256-handtekeningtekenreeks van het formulier: {URL-encoded-resourceURI} + "\n" + expiry. Belangrijk: De sleutel wordt gedecodeerd uit base64 en gebruikt als sleutel om de HMAC-SHA256-berekening uit te voeren.
{expiry}	UTF8-tekenreeksen voor het aantal seconden sinds het tijdvak 00:00:00 UTC op 1 januari 1970.
{URL-encoded-resourceURI}	URL-codering in kleine letters van {ID_Scope}/registrations/{registration_id}
{policyName}	Voor de Apparaat-API is dit beleid altijd 'registratie'.

Het volgende Python-codefragment toont een functie generate_sas_token die het token berekent van de invoer uri, key, policy_nameexpiry voor een afzonderlijke inschrijving met behulp van een verificatietype symmetrische sleutel.

from base64 import b64encode, b64decode, encode 
from hashlib import sha256 
from time import time 
from urllib.parse import quote_plus, urlencode 
from hmac import HMAC 

 def generate_sas_token(uri, key, policy_name, expiry=3600): 
    ttl = time() + expiry 
    sign_key = "%s\n%d" % ((quote_plus(uri)), int(ttl)) 
    signature = b64encode(HMAC(b64decode(key), sign_key.encode('utf-8'), sha256).digest()) 

    rawtoken = { 
        'sr' :  uri, 
        'sig': signature, 
        'se' : str(int(ttl)), 
        'skn' : policy_name 
    } 

    return 'SharedAccessSignature ' + urlencode(rawtoken) 

print(generate_sas_token("myIdScope/registrations/mydeviceregistrationid", "00mysymmetrickey", "registration"))

Het resultaat moet er ongeveer uitzien als de volgende uitvoer:

SharedAccessSignature sr=myIdScope%2Fregistrations%2Fmydeviceregistrationid&sig=SDpdbUNk%2F1DSjEpeb29BLVe6gRDZI7T41Y4BPsHHoUg%3D&se=1630175722&skn=registration 

In het volgende voorbeeld ziet u hoe de handtekening voor gedeelde toegang vervolgens wordt gebruikt om te verifiëren met de Apparaat-API.

curl -L -i -X PUT -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: [token]' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[ID_Scope]/registrations/[registration_id]/register?api-version=2021-06-01 

Als u een inschrijvingsgroep op basis van een symmetrische sleutel gebruikt, moet u eerst een device symmetric sleutel genereren met behulp van de inschrijvingsgroepssleutel. Gebruik de primaire of secundaire sleutel van de inschrijvingsgroep om een HMAC-SHA256 van de registratie-id voor het apparaat te berekenen. Het resultaat wordt vervolgens geconverteerd naar de Base64-indeling om de afgeleide apparaatsleutel te verkrijgen. Zie Apparaten inrichten met behulp van symmetrische sleutelinschrijvingsgroepen voor meer informatie over het weergeven van codevoorbeelden. Zodra de symmetrische sleutel van het apparaat is afgeleid, kunt u het apparaat registreren met behulp van de vorige voorbeelden.

Waarschuwing

Om te voorkomen dat u de groepshoofdsleutel in uw apparaatcode opneemt, moet het proces van het afleiden van de apparaatsleutel worden uitgevoerd op het apparaat.

Verificatie op basis van certificaat

Als u een afzonderlijke inschrijvings- of inschrijvingsgroep hebt ingesteld voor verificatie op basis van X.509-certificaten, moet het apparaat het uitgegeven X.509-certificaat gebruiken om aan de apparaat-API te bevestigen. Raadpleeg de volgende artikelen over het instellen van de inschrijving en het genereren van het apparaatcertificaat.

• Quickstart: Gesimuleerd X.509-apparaat inrichten voor Azure IoT Hub

• Quickstart: X.509-apparaten inschrijven bij Azure Device Provisioning Service

Zodra de inschrijving is ingesteld en het apparaatcertificaat is uitgegeven, ziet u in het volgende voorbeeld hoe u zich kunt verifiëren bij de Apparaat-API met het X.509-certificaat van het apparaat.

curl -L -i -X PUT –cert ./[device_cert].pem –key ./[device_cert_private_key].pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[ID_Scope]/registrations/[registration_id]/register?api-version=2021-06-01 

Service-API-verificatie

De service-API wordt gebruikt om de registratiestatus op te halen en apparaatregistraties te verwijderen. De service wordt ook gebruikt door back-end-apps om programmatisch zowel afzonderlijke groepen als inschrijvingsgroepen te beheren. De Service-API ondersteunt verificatie op basis van sleutels voor back-end-apps.

U moet over de juiste machtigingen beschikken om toegang te krijgen tot een van de service-API-eindpunten. Een back-end-app moet bijvoorbeeld een token bevatten met beveiligingsreferenties, samen met elk bericht dat naar de service wordt verzonden.

Azure IoT Hub Device Provisioning Service verleent toegang tot eindpunten door het token te verifiëren op basis van het beleid voor gedeelde toegang. Beveiligingsreferenties, zoals symmetrische sleutels, worden nooit via de kabel verzonden.

Toegangsbeheer en machtigingen

U kunt op de volgende manieren machtigingen verlenen:

• Autorisatiebeleid voor gedeelde toegang. Beleid voor gedeelde toegang kan elke combinatie van machtigingen verlenen. U kunt beleidsregels definiëren in Azure Portal of programmatisch met behulp van de REST API's van Device Provisioning Service. Een nieuw gemaakte inrichtingsservice heeft het volgende standaardbeleid:

• provisioningserviceowner: Beleid met alle machtigingen. Zie machtigingen voor gedetailleerde informatie.

Notitie

De Device Provisioning Service-resourceprovider wordt beveiligd via uw Azure-abonnement, net als alle providers in Azure Resource Manager.

Zie de volgende sectie voor meer informatie over het maken en gebruiken van beveiligingstokens.

HTTP is het enige ondersteunde protocol en implementeert verificatie door een geldig token op te geven in de header van de autorisatieaanvraag .

voorbeeld

SharedAccessSignature sr = 
   mydps.azure-devices-provisioning.net&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501&skn=provisioningserviceowner`\

Notitie

De SDK's van Azure IoT Device Provisioning Service genereren automatisch tokens bij het maken van verbinding met de service.

Beveiligingstokens

Device Provisioning Service gebruikt beveiligingstokens om services te verifiëren om te voorkomen dat sleutels op de kabel worden verzonden. Bovendien zijn beveiligingstokens beperkt in de geldigheid en het bereik van de tijd. Azure IoT Device Provisioning Service SDK's genereren automatisch tokens zonder speciale configuratie. Voor sommige scenario's moet u beveiligingstokens rechtstreeks genereren en gebruiken. Dergelijke scenario's omvatten het directe gebruik van het HTTP-oppervlak.

Structuur van beveiligingstokens

U gebruikt beveiligingstokens om tijdgebonden toegang te verlenen aan services voor specifieke functionaliteit in IoT Device Provisioning Service. Om autorisatie te krijgen om verbinding te maken met de inrichtingsservice, moeten services beveiligingstokens verzenden die zijn ondertekend met een gedeelde toegang of een symmetrische sleutel.

Een token dat is ondertekend met een gedeelde toegangssleutel verleent toegang tot alle functionaliteit die is gekoppeld aan de machtigingen voor gedeeld toegangsbeleid.

Het beveiligingstoken heeft de volgende indeling:

SharedAccessSignature sig={signature}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI}

Dit zijn de verwachte waarden

Waarde	Omschrijving
{signature}	Een HMAC-SHA256-handtekeningtekenreeks van het formulier: {URL-encoded-resourceURI} + "\n" + expiry. Belangrijk: De sleutel wordt gedecodeerd uit base64 en gebruikt als sleutel om de HMAC-SHA256-berekening uit te voeren.
{vervaldatum}	UTF8-tekenreeksen voor het aantal seconden sinds het tijdvak 00:00:00 UTC op 1 januari 1970.
{URL-gecodeerde-resourceURI}	URL-codering van kleine letters van de resource-URI met kleine letters. URI-voorvoegsel (per segment) van de eindpunten die kunnen worden geopend met dit token, te beginnen met de hostnaam van de IoT Device Provisioning Service (geen protocol). Bijvoorbeeld mydps.azure-devices-provisioning.net.
{policyName}	De naam van het beleid voor gedeelde toegang waarnaar dit token verwijst.

Notitie

Het URI-voorvoegsel wordt berekend op segment en niet op teken. Dit is bijvoorbeeld /a/b een voorvoegsel voor /a/b/c maar niet voor /a/bc.

Het volgende Node.js-fragment toont een functie met de naam generateSasToken waarmee het token wordt berekend op basis van de invoer resourceUri, signingKey, policyName, expiresInMins. In de volgende secties wordt beschreven hoe u de verschillende invoer voor de verschillende tokengebruiksscenario's initialiseert.

var generateSasToken = function(resourceUri, signingKey, policyName, expiresInMins) {
    resourceUri = encodeURIComponent(resourceUri);

    // Set expiration in seconds
    var expires = (Date.now() / 1000) + expiresInMins * 60;
    expires = Math.ceil(expires);
    var toSign = resourceUri + '\n' + expires;

    // Use crypto
    var hmac = crypto.createHmac('sha256', new Buffer(signingKey, 'base64'));
    hmac.update(toSign);
    var base64UriEncoded = encodeURIComponent(hmac.digest('base64'));

    // Construct authorization string
    var token = "SharedAccessSignature sr=" + resourceUri + "&sig="
    + base64UriEncoded + "&se=" + expires + "&skn="+ policyName;
    return token;
};

Ter vergelijking: de equivalente Python-code voor het genereren van een beveiligingstoken is:

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib.parse import quote_plus, urlencode
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600):
    ttl = time() + expiry
    sign_key = "%s\n%d" % ((quote_plus(uri)), int(ttl))
    print sign_key
    signature = b64encode(HMAC(b64decode(key), sign_key, sha256).digest())

    rawtoken = {
        'sr' :  uri,
        'sig': signature,
        'se' : str(int(ttl)),
        'skn' : policy_name
    }

    return 'SharedAccessSignature ' + urlencode(rawtoken)

Notitie

Omdat de geldigheidsduur van het token wordt gevalideerd op IoT Device Provisioning Service-machines, moet de afwijking op de klok van de machine die het token genereert minimaal zijn.

Beveiligingstokens van serviceonderdelen gebruiken

Serviceonderdelen kunnen alleen beveiligingstokens genereren met behulp van gedeeld toegangsbeleid dat de juiste machtigingen verleent, zoals eerder is uitgelegd.

Dit zijn de servicefuncties die beschikbaar zijn op de eindpunten:

Eindpunt	Functionaliteit
{your-service}.azure-devices-provisioning.net/enrollments	Biedt apparaatinschrijvingsbewerkingen met Device Provisioning Service.
{your-service}.azure-devices-provisioning.net/enrollmentGroups	Biedt bewerkingen voor het beheren van apparaatinschrijvingsgroepen.
{your-service}.azure-devices-provisioning.net/registrations/{id}	Biedt bewerkingen voor het ophalen en beheren van de status van apparaatregistraties.

Een service die wordt gegenereerd met behulp van een vooraf gemaakt gedeeld toegangsbeleid dat wordt aangeroepen enrollmentread , maakt bijvoorbeeld een token met de volgende parameters:

• resource-URI: {mydps}.azure-devices-provisioning.net,
• ondertekeningssleutel: een van de sleutels van het enrollmentread beleid,
• beleidsnaam: enrollmentread,
• verlooptijd.backn

var endpoint ="mydps.azure-devices-provisioning.net";
var policyName = 'enrollmentread'; 
var policyKey = '...';

var token = generateSasToken(endpoint, policyKey, policyName, 60);

Het resultaat, dat toegang verleent om alle inschrijvingsrecords te lezen, is:

SharedAccessSignature sr=mydps.azure-devices-provisioning.net&sig=JdyscqTpXdEJs49elIUCcohw2DlFDR3zfH5KqGJo4r4%3D&se=1456973447&skn=enrollmentread

SDK's en voorbeelden

• Release van Azure IoT SDK voor Java Preview
  • Voorbeeld
• Microsoft Azure IoT SDK's voor .NET Preview-release
  • Voorbeeld

Naslagonderwerpen:

De volgende naslagonderwerpen bevatten meer informatie over het beheren van de toegang tot uw IoT Device Provisioning Service.

Machtigingen voor Device Provisioning Service

De volgende tabel bevat de machtigingen die u kunt gebruiken om de toegang tot uw IoT Device Provisioning Service te beheren.

Machtiging	Aantekeningen
ServiceConfig	Verleent toegang om de serviceconfiguraties te wijzigen. Deze machtiging wordt gebruikt door back-endcloudservices.
EnrollmentRead	Verleent leestoegang tot de apparaatinschrijvingen en inschrijvingsgroepen. Deze machtiging wordt gebruikt door back-endcloudservices.
EnrollmentWrite	Verleent schrijftoegang tot de apparaatinschrijvingen en inschrijvingsgroepen. Deze machtiging wordt gebruikt door back-endcloudservices.
RegistrationStatusRead	Verleent leestoegang tot de apparaatregistratiestatus. Deze machtiging wordt gebruikt door back-endcloudservices.
RegistrationStatusWrite	Verleent verwijderingstoegang tot de apparaatregistratiestatus. Deze machtiging wordt gebruikt door back-endcloudservices.