Kontrollera åtkomst till Azure IoT Hub Device Provisioning Service

I den här artikeln beskrivs de tillgängliga alternativen för att skydda IoT Device Provisioning-tjänsten. Etableringstjänsten använder autentisering och behörigheter för att bevilja åtkomst till varje slutpunkt. Med behörigheter kan autentiseringsprocessen begränsa åtkomsten till en tjänstinstans baserat på funktioner.

I den här artikeln beskrivs:

  • Autentiseringsprocessen och de token som etableringstjänsten använder för att verifiera behörigheter mot både tjänstens och enhetens REST-API:er.

  • De olika behörigheter som du kan bevilja till en backend-app för att få åtkomst till tjänst-API:et.

Autentisering

Enhets-API:et stöder nyckelbaserad och X.509-certifikatbaserad enhetsautentisering.

Tjänst-API:et stöder nyckelbaserad autentisering för serverappsappar.

När du använder nyckelbaserad autentisering använder Device Provisioning Service säkerhetstoken för att autentisera tjänster för att undvika att skicka nycklar via kabel. Dessutom är säkerhetstoken begränsade i tidsenlighet och omfattning. AZURE IoT Device Provisioning-SDK:er genererar automatiskt token utan att någon särskild konfiguration krävs.

I vissa fall kan du behöva använda REST-API:erna för HTTP Device Provisioning Service direkt, utan att använda DEDK:erna. I följande avsnitt beskrivs hur du autentiserar direkt mot REST-API:erna.

API-autentisering för enhet

Enhets-API:et används av enheter för attestera till Device Provisioning-tjänsten och ta emot en IoT Hub anslutning.

Anteckning

För att kunna ta emot en autentiserad anslutning måste enheterna först registreras i Device Provisioning-tjänsten via en registrering. Använd tjänst-API:et för att programmatiskt registrera en enhet via en registrering.

En enhet måste autentisera till enhets-API:et som en del av etableringsprocessen. Den metod som en enhet använder för att autentisera definieras när du ställer in en registreringsgrupp eller enskild registrering. Oavsett autentiseringsmetod måste enheten utfärda en HTTPS PUT till följande URL för att etablera sig själv.

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

Om du använder nyckelbaserad autentisering skickas en säkerhetstoken i rubriken http-auktoriseringsbegäran   i följande format:

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

Säkerhetstokenstruktur för nyckelbaserad autentisering

Säkerhetstoken skickas i rubriken http-auktoriseringsbegäran   i följande format:

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

De förväntade värdena är:

Värde Beskrivning
{signature} En HMAC-SHA256-signatursträng i formuläret:  {URL-encoded-resourceURI} + "\n" + expiry . ** Viktigt!** Nyckeln avkodas från base64 och används som nyckel för att utföra HMAC-SHA256-beräkningen.
{expiry} UTF8-strängar för antal sekunder sedan epoken 00:00:00 UTC den 1 januari 1970.
{URL-encoded-resourceURI} GEMEN URL-kodning av {ID_Scope}/registrations/{registration_id}
{policyName} För enhets-API:et är den här principen alltid "registrering".

Följande Python-kodfragment visar en funktion med namnet som beräknar token från indata , , , för en enskild registrering med hjälp av  generate_sas_token    uri key en policy_name expiry autentiseringstyp med symmetrisk nyckel.


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"))

Resultatet bör likna följande utdata:


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

I följande exempel visas hur signaturen för delad åtkomst sedan används för att autentisera med enhets-API:et.


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 

Om du använder en symmetrisk nyckelbaserad registreringsgrupp måste du först generera en nyckel med hjälp device symmetric av registreringsgruppsnyckeln. Använd registreringsgruppens primära eller sekundära nyckel för att beräkna en HMAC-SHA256 för enhetens registrerings-ID. Resultatet konverteras sedan till Base64-format för att hämta den härledda enhetsnyckeln. Om du vill visa kodexempel kan du se Så här etablerar du enheter med registreringsgrupper med symmetrisk nyckel. När enhetens symmetriska nyckel har härletts kan du registrera enheten med hjälp av föregående exempel.

Varning

För att undvika att ta med huvudnyckeln för gruppen i enhetskoden bör processen för att härleda enhetsnyckeln utföras från enheten.

Certifikatbaserad autentisering

Om du har skapat en enskild registrering eller registreringsgrupp för X.509-certifikatbaserad autentisering måste enheten använda sitt utfärdade X.509-certifikat för attestering till enhets-API:et. Läs följande artiklar om hur du ställer in registreringen och genererar enhetscertifikatet.

När registreringen har ställts in och enhetscertifikatet utfärdats visar följande exempel hur du autentiserar till enhets-API:et med enhetens X.509-certifikat.


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 

Api-autentisering för tjänst

Tjänst-API:et används för att hämta registreringstillstånd och ta bort enhetsregistreringar. Tjänsten används också av backend-appar för att programmatiskt hantera både enskilda grupper och registreringsgrupper. Tjänst-API:et stöder nyckelbaserad autentisering för serverappsappar.

Du måste ha rätt behörigheter för att komma åt någon av tjänst-API-slutpunkterna. En backend-app måste till exempel innehålla en token som innehåller säkerhetsautentiseringsuppgifter tillsammans med varje meddelande som den skickar till tjänsten.

Azure IoT Hub Device Provisioning Service ger åtkomst till slutpunkter genom att verifiera token mot principerna för delad åtkomst. Säkerhetsautentiseringsuppgifter, till exempel symmetriska nycklar, skickas aldrig via kabel.

Åtkomstkontroll och behörigheter

Du kan bevilja behörigheter på följande sätt:

  • Auktoriseringsprinciper för delad åtkomst. Principer för delad åtkomst kan bevilja valfri kombination av behörigheter. Du kan definiera principer i Azure Portal, eller programmässigt med hjälp av REST-API:erna för enhetsetableringstjänsten. En nyligen skapad etableringstjänst har följande standardprincip:

  • provisioningserviceowner: Princip med alla behörigheter. Se behörigheter för detaljerad information.

Anteckning

Resursprovidern för Enhetsetableringstjänsten skyddas via din Azure-prenumeration, precis som alla leverantörer i Azure Resource Manager.

Mer information om hur du skapar och använder säkerhetstoken finns i nästa avsnitt.

HTTP är det enda protokoll som stöds och implementerar autentisering genom att inkludera en giltig token i rubriken Authorization request (Auktoriseringsbegäran).

Exempel

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

Anteckning

AZURE IoT Device Provisioning Service-SDK:erna genererar automatiskt token vid anslutning till tjänsten.

Säkerhetstoken

Device Provisioning Service använder säkerhetstoken för att autentisera tjänster för att undvika att skicka nycklar via kabeln. Dessutom är säkerhetstoken begränsade i tidsenlighet och omfattning. AZURE IoT Device Provisioning Service-SDK:er genererar automatiskt token utan att någon särskild konfiguration krävs. Vissa scenarier kräver att du genererar och använder säkerhetstoken direkt. Sådana scenarier omfattar direkt användning av HTTP-ytan.

Säkerhetstokenstruktur

Du använder säkerhetstoken för att bevilja tidsbunden åtkomst för tjänster till specifika funktioner i IoT Device Provisioning-tjänsten. För att få behörighet att ansluta till etableringstjänsten måste tjänsterna skicka säkerhetstoken signerade med antingen delad eller symmetrisk nyckel.

En token som signerats med en delad åtkomstnyckel ger åtkomst till alla funktioner som är associerade med behörigheter för principen för delad åtkomst.

Säkerhetstoken har följande format:

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

Här är de förväntade värdena:

Värde Beskrivning
{signature} En HMAC-SHA256-signatursträng i formuläret: {URL-encoded-resourceURI} + "\n" + expiry . Viktigt! Nyckeln avkodas från base64 och används som nyckel för att utföra HMAC-SHA256-beräkningen.
{expiry} UTF8-strängar för antal sekunder sedan epoken 00:00:00 UTC den 1 januari 1970.
{URL-kodad-resourceURI} GEMEN URL-kodning av resurs-URI i gemener. URI-prefix (efter segment) för de slutpunkter som kan nås med denna token, från och med värdnamnet för IoT Device Provisioning Service (inget protokoll). Till exempel mydps.azure-devices-provisioning.net.
{policyName} Namnet på principen för delad åtkomst som denna token refererar till.

Anteckning

URI-prefixet beräknas efter segment och inte efter tecken. Till exempel /a/b är ett prefix för men inte för /a/b/c /a/bc .

Följande kodfragment Node.js en funktion med namnet generateSasToken som beräknar token från indata resourceUri, signingKey, policyName, expiresInMins . I nästa avsnitt beskrivs hur du initierar olika indata för olika tokenanvändningsfall.

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;
};

Som jämförelse är motsvarande Python-kod för att generera en säkerhetstoken:

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib 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)

Anteckning

Eftersom tokens giltighet verifieras på IoT Device Provisioning Service-datorer måste fördringstiden på klockan för den dator som genererar token vara minimal.

Använda säkerhetstoken från tjänstkomponenter

Tjänstkomponenter kan bara generera säkerhetstoken med hjälp av principer för delad åtkomst som beviljar lämpliga behörigheter enligt tidigare förklaring.

Här är de tjänstfunktioner som exponeras på slutpunkterna:

Slutpunkt Funktioner
{your-service}.azure-devices-provisioning.net/enrollments Tillhandahåller enhetsregistreringsåtgärder med Device Provisioning-tjänsten.
{your-service}.azure-devices-provisioning.net/enrollmentGroups Tillhandahåller åtgärder för att hantera grupper för enhetsregistrering.
{your-service}.azure-devices-provisioning.net/registrations/{id} Tillhandahåller åtgärder för att hämta och hantera status för enhetsregistreringar.

Till exempel skulle en tjänst som genererats med en i förväg skapad princip för delad åtkomst med namnet enrollmentread skapa en token med följande parametrar:

  • resurs-URI: {mydps}.azure-devices-provisioning.net ,
  • signeringsnyckel: en av enrollmentread principnycklarna,
  • principnamn: enrollmentread ,
  • any expiration time.backn

Skapa en princip för delad åtkomst för instansen av enhetsetableringstjänsten i portalen

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

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

Resultatet, som skulle ge åtkomst att läsa alla registreringsposter, skulle bli:

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

Referensavsnitt:

Följande referensavsnitt innehåller mer information om hur du styr åtkomsten till IoT Device Provisioning-tjänsten.

Behörigheter för Enhetsetableringstjänsten

I följande tabell visas de behörigheter som du kan använda för att styra åtkomsten till IoT Device Provisioning-tjänsten.

Behörighet Kommentarer
ServiceConfig Ger åtkomst till att ändra tjänstkonfigurationerna.
Den här behörigheten används av backend-molntjänster.
EnrollmentRead Ger läsbehörighet till enhetsregistreringar och registreringsgrupper.
Den här behörigheten används av backend-molntjänster.
EnrollmentWrite Ger skrivåtkomst till enhetsregistreringar och registreringsgrupper.
Den här behörigheten används av backend-molntjänster.
RegistrationStatusRead Ger läsbehörighet till enhetsregistreringsstatusen.
Den här behörigheten används av backend-molntjänster.
RegistrationStatusWrite Ger borttagningsåtkomst till enhetsregistreringsstatusen.
Den här behörigheten används av backend-molntjänster.