Kontrollera åtkomsten till IoT Hub med signaturer för delad åtkomst

IoT Hub använder SAS-token (signatur för delad åtkomst) för att autentisera enheter och tjänster för att undvika att skicka nycklar på kabeln. Du använder SAS-token för att bevilja tidsbegränsad åtkomst till enheter och tjänster till specifika funktioner i IoT Hub. För att få auktorisering för att ansluta till IoT Hub måste enheter och tjänster skicka SAS-token signerade med antingen delad åtkomst eller symmetrisk nyckel. Symmetriska nycklar lagras med en enhetsidentitet i identitetsregistret.

I den här artikeln beskrivs:

• De olika behörigheter som du kan bevilja en klient för åtkomst till din IoT-hubb.
• De token som IoT Hub använder för att verifiera behörigheter.
• Så här omfångsbegränsar du autentiseringsuppgifter för att begränsa åtkomsten till specifika resurser.
• Mekanismer för anpassad enhetsautentisering som använder befintliga enhetsidentitetsregister eller autentiseringsscheman.

Kommentar

Några av de funktioner som nämns i den här artikeln, t.ex. moln till enhet-meddelanden, enhetstvillingar och enhetshantering, är bara tillgängliga på IoT Hubs standardnivå. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

IoT Hub använder behörigheter för att bevilja åtkomst till varje IoT Hub-slutpunkt. Behörigheter begränsar åtkomsten till en IoT-hubb baserat på funktioner. Du måste ha rätt behörighet för att få åtkomst till någon av IoT Hub-slutpunkterna. En enhet måste till exempel innehålla en token som innehåller säkerhetsautentiseringsuppgifter tillsammans med varje meddelande den skickar till IoT Hub. Signeringsnycklarna, som enhetens symmetriska nycklar, skickas dock aldrig via kabeln.

Autentisering och auktorisering

Autentisering är en process för att bevisa att du är den du säger att du är. Autentisering verifierar identiteten för en användare eller enhet till IoT Hub. Det förkortas ibland till AuthN. Auktorisering är processen för att bekräfta behörigheter för en autentiserad användare eller enhet på IoT Hub. Den anger vilka resurser och kommandon du får åtkomst till och vad du kan göra med dessa resurser och kommandon. Auktorisering förkortas ibland till AuthZ.

I den här artikeln beskrivs autentisering och auktorisering med signaturer för delad åtkomst, vilket gör att du kan gruppera behörigheter och bevilja dem till program med hjälp av åtkomstnycklar och signerade säkerhetstoken. Du kan också använda symmetriska nycklar eller delade åtkomstnycklar för att autentisera en enhet med IoT Hub. SAS-token ger autentisering för varje anrop som görs av enheten till IoT Hub genom att koppla den symmetriska nyckeln till varje anrop.

Åtkomstkontroll och behörigheter

Använd principer för delad åtkomst för åtkomst på IoT-hubbnivå och använd endast de enskilda enhetsautentiseringsuppgifterna för att begränsa åtkomsten till den enheten.

Principer för delad åtkomst på IoT-hubbnivå

Principer för delad åtkomst kan ge valfri kombination av behörigheter. Du kan definiera principer i Azure-portalen programmatiskt med hjälp av REST-API:er för IoT Hub-resurser eller med hjälp av azure CLI az iot hub policy-kommandot. En nyligen skapad IoT-hubb har följande standardprinciper:

Princip för delad åtkomst	Behörigheter
iothubowner	Alla behörigheter
service	ServiceConnect-behörigheter
enhet	DeviceConnect-behörigheter
registryRead	RegistryRead-behörigheter
registryReadWrite	RegistryRead- och RegistryWrite-behörigheter

Du kan använda följande behörigheter för att styra åtkomsten till din IoT-hubb:

• ServiceConnect-behörigheten används av backend-molntjänster och ger följande åtkomst:

  • Åtkomst till molntjänstriktad kommunikation och övervakning av slutpunkter.
  • Ta emot meddelanden från enhet till moln, skicka meddelanden från molnet till enheten och hämta motsvarande leveransbekräftelser.
  • Hämta leveransbekräftelser för filuppladdningar.
  • Få åtkomst till tvillingar för att uppdatera taggar och önskade egenskaper, hämta rapporterade egenskaper och köra frågor.

• Behörigheten DeviceConnect används av enheter och ger följande åtkomst:

  • Åtkomst till enhetsriktade slutpunkter.
  • Skicka meddelanden från enhet till moln och ta emot meddelanden från molnet till enheten.
  • Utför filuppladdning.
  • Ta emot önskade egenskapsaviseringar för enhetstvillingar och uppdatera rapporterade egenskaper för enhetstvillingar.

• RegistryRead-behörigheten används av backend-molntjänster och ger följande åtkomst:

  • Läs åtkomst till identitetsregistret. Mer information finns i Identitetsregister.

• Behörigheten RegistryReadWrite används av backend-molntjänster och ger följande åtkomst:

  • Läs- och skrivåtkomst till identitetsregistret. Mer information finns i Identitetsregister.

Säkerhetsautentiseringsuppgifter per enhet

Varje IoT-hubb har ett identitetsregister som lagrar information om de enheter och moduler som tillåts ansluta till den. Innan en enhet eller modul kan ansluta måste det finnas en post för enheten eller modulen i IoT-hubbens identitetsregister. En enhet eller modul autentiserar med IoT-hubben baserat på autentiseringsuppgifter som lagras i identitetsregistret.

När du registrerar en enhet för att använda SAS-tokenautentisering hämtar den enheten två symmetriska nycklar. Symmetriska nycklar ger DeviceConnect-behörigheten för den associerade enhetsidentiteten.

Använda SAS-token från tjänster

Tjänster kan generera SAS-token med hjälp av en princip för delad åtkomst som definierar lämpliga behörigheter enligt beskrivningen tidigare i avsnittet Åtkomstkontroll och behörigheter .

Till exempel skulle en tjänst som använder den förskapade principen för delad åtkomst med namnet registryRead skapa en token med följande parametrar:

• resurs-URI: {IoT hub name}.azure-devices.net,
• signeringsnyckel: en av principernas registryRead nycklar,
• principnamn: registryRead,
• förfallotid.

Följande kod skapar till exempel en SAS-token i Node.js:

var endpoint = "myhub.azure-devices.net";
var policyName = 'registryRead';
var policyKey = '...';

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

Resultatet, som ger åtkomst till att läsa alla enhetsidentiteter i identitetsregistret, skulle vara:

SharedAccessSignature sr=myhub.azure-devices.net&sig=JdyscqTpXdEJs49elIUCcohw2DlFDR3zfH5KqGJo4r4%3D&se=1456973447&skn=registryRead

Fler exempel finns i Generera SAS-token.

För tjänster beviljar SAS-token endast behörigheter på IoT Hub-nivå. En tjänst som autentiserar med en token baserat på tjänstprincipen kan alltså utföra alla åtgärder som beviljas av ServiceConnect-behörigheten. Dessa åtgärder omfattar att ta emot meddelanden från enhet till moln, skicka meddelanden från moln till enhet och så vidare. Om du vill ge mer detaljerad åtkomst till dina tjänster, till exempel begränsa en tjänst till att endast skicka meddelanden från moln till enhet, kan du använda Microsoft Entra-ID. Mer information finns i Autentisera med Microsoft Entra-ID.

Använda SAS-token från enheter

Det finns två sätt att hämta DeviceConnect-behörigheter med IoT Hub med SAS-token: använda en symmetrisk enhetsnyckel från identitetsregistret eller använda en delad åtkomstnyckel.

Alla funktioner som är tillgängliga från enheter exponeras avsiktligt på slutpunkter med prefixet /devices/{deviceId}.

De enhetsriktade slutpunkterna är (oavsett protokoll):

Slutpunkt	Funktioner
{iot hub name}/devices/{deviceId}/messages/events	Skicka meddelanden från enhet till moln.
{iot hub name}/devices/{deviceId}/messages/devicebound	Ta emot meddelanden från moln till enhet.

Använda en symmetrisk nyckel i identitetsregistret

När du använder en enhetsidentitets symmetriska nyckel för att generera en token utelämnas elementet policyName (skn) i token.

Till exempel bör en token som skapats för att komma åt alla enhetsfunktioner ha följande parametrar:

• resurs-URI: {IoT hub name}.azure-devices.net/devices/{device id},
• signeringsnyckel: valfri symmetrisk nyckel för identiteten {device id} ,
• inget principnamn,
• förfallotid.

Följande kod skapar till exempel en SAS-token i Node.js:

var endpoint ="myhub.azure-devices.net/devices/device1";
var deviceKey ="...";

var token = generateSasToken(endpoint, deviceKey, null, 60);

Resultatet, som ger åtkomst till alla funktioner för device1, skulle vara:

SharedAccessSignature sr=myhub.azure-devices.net%2fdevices%2fdevice1&sig=13y8ejUk2z7PLmvtwR5RqlGBOVwiq7rQR3WZ5xZX3N4%3D&se=1456971697

Fler exempel finns i Generera SAS-token.

Använda en princip för delad åtkomst för att få åtkomst för en enhets räkning

När du skapar en token från en princip för delad åtkomst anger du skn fältet till namnet på principen. Den här principen måste ge DeviceConnect-behörigheten.

De två huvudscenarierna för att använda principer för delad åtkomst för att komma åt enhetsfunktioner är:

• cloud protocol gateways,
• token-tjänster som används för att implementera anpassade autentiseringsscheman.

Eftersom principen för delad åtkomst potentiellt kan bevilja åtkomst för att ansluta som vilken enhet som helst är det viktigt att använda rätt resurs-URI när du skapar SAS-token. Den här inställningen är särskilt viktig för tokentjänster, som måste begränsa token till en specifik enhet med hjälp av resurs-URI:n. Den här punkten är mindre relevant för protokollgatewayer eftersom de redan förmedlar trafik för alla enheter.

Till exempel skulle en tokentjänst med den förskapade principen för delad åtkomst som kallas enhet skapa en token med följande parametrar:

• resurs-URI: {IoT hub name}.azure-devices.net/devices/{device id},
• signeringsnyckel: en av principernas device nycklar,
• principnamn: device,
• förfallotid.

Följande kod skapar till exempel en SAS-token i Node.js:

var endpoint ="myhub.azure-devices.net/devices/device1";
var policyName = 'device';
var policyKey = '...';

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

Resultatet, som ger åtkomst till alla funktioner för device1, skulle vara:

SharedAccessSignature sr=myhub.azure-devices.net%2fdevices%2fdevice1&sig=13y8ejUk2z7PLmvtwR5RqlGBOVwiq7rQR3WZ5xZX3N4%3D&se=1456971697&skn=device

En protokollgateway kan använda samma token för alla enheter genom att ange resurs-URI:n till myhub.azure-devices.net/devices.

Fler exempel finns i Generera SAS-token.

Skapa en tokentjänst för att integrera befintliga enheter

Du kan använda IoT Hub-identitetsregistret för att konfigurera säkerhetsautentiseringsuppgifter per enhet eller per modul och åtkomstkontroll med hjälp av token. Om en IoT-lösning redan har ett anpassat identitetsregister och/eller autentiseringsschema bör du överväga att skapa en tokentjänst för att integrera den här infrastrukturen med IoT Hub. På så sätt kan du använda andra IoT-funktioner i din lösning.

En tokentjänst är en anpassad molntjänst. Den använder en princip för delad åtkomst i IoT Hub med behörigheten DeviceConnect för att skapa token med enhetsomfattning eller modulomfattning. Dessa token gör det möjligt för en enhet eller modul att ansluta till din IoT-hubb.

Här är de viktigaste stegen i tokentjänstmönstret:

1. Skapa en princip för delad åtkomst i IoT Hub med behörigheten DeviceConnect för din IoT-hubb. Du kan skapa den här principen i Azure-portalen eller programmatiskt. Tokentjänsten använder den här principen för att signera de token som skapas.

2. När en enhet eller modul behöver komma åt din IoT-hubb begär den en signerad token från din tokentjänst. Enheten kan autentisera med ditt anpassade identitetsregister/autentiseringsschema för att fastställa den enhets-/modulidentitet som tokentjänsten använder för att skapa token.

3. Tokentjänsten returnerar en token. Token skapas med hjälp /devices/{deviceId} av eller /devices/{deviceId}/modules/{moduleId} som resourceURI, med deviceId som enheten autentiseras och moduleId som modulen autentiseras. Tokentjänsten använder principen för delad åtkomst för att konstruera token.

4. Enheten/modulen använder token direkt med IoT-hubben.

Kommentar

Du kan använda .NET-klassen SharedAccessSignatureBuilder eller Java-klassen IotHubServiceSasToken för att skapa en token i din tokentjänst.

Tokentjänsten kan ange förfallodatum för token som önskat. När token upphör att gälla bryter IoT-hubben enheten/modulanslutningen. Sedan måste enheten/modulen begära en ny token från tokentjänsten. En kort förfallotid ökar belastningen på både enheten/modulen och tokentjänsten.

För att en enhet/modul ska kunna ansluta till din hubb måste du fortfarande lägga till den i IoT Hub-identitetsregistret , även om den använder en token och inte en nyckel för att ansluta. Därför kan du fortsätta att använda åtkomstkontroll per enhet/per modul genom att aktivera eller inaktivera enhets-/modulidentiteter i identitetsregistret. Den här metoden minskar risken för att använda token med långa förfallotider.

Jämförelse med en anpassad gateway

Mönstret för tokentjänsten är det rekommenderade sättet att implementera ett anpassat identitetsregister/autentiseringsschema med IoT Hub. Det här mönstret rekommenderas eftersom IoT Hub fortsätter att hantera merparten av lösningstrafiken. Men om det anpassade autentiseringsschemat är så sammanflätat med protokollet kan du behöva en anpassad gateway för att bearbeta all trafik. Ett exempel på ett sådant scenario är att använda TLS (Transport Layer Security) och i förväg delade nycklar (PSK:er). Mer information finns i Hur en IoT Edge-enhet kan användas som en gateway.

Generera SAS-token

Azure IoT SDK:er genererar automatiskt token, men vissa scenarier kräver att du genererar och använder SAS-token direkt, inklusive:

• Direkt användning av MQTT-, AMQP- eller HTTPS-ytorna.

• Implementeringen av tokentjänstmönstret, enligt beskrivningen i avsnittet Skapa en tokentjänst .

En token som är signerad med en nyckel för delad åtkomst ger åtkomst till alla funktioner som är associerade med behörigheterna för principen för delad åtkomst. En token som är signerad med en enhetsidentitets symmetriska nyckel ger endast DeviceConnect-behörigheten för den associerade enhetsidentiteten.

Det här avsnittet innehåller exempel på hur du genererar SAS-token på olika kodspråk. Du kan också generera SAS-token med CLI-tilläggskommandot az iot hub generate-sas-token eller Azure IoT Hub-tillägget för Visual Studio Code.

SAS-tokenstruktur

En SAS-token har följande format:

SharedAccessSignature sig={signature-string}&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.
{resourceURI}	URI-prefix (efter segment) för de slutpunkter som kan nås med den här token, från och med värdnamnet för IoT Hub (inget protokoll). SAS-token som beviljats serverdelstjänster är begränsade till IoT Hub-nivån. till exempel myHub.azure-devices.net. SAS-token som beviljats enheter måste vara begränsade till en enskild enhet. till exempel myHub.azure-devices.net/devices/device1.
{expiry}	UTF8-strängar för antal sekunder sedan epoken 00:00:00 UTC den 1 januari 1970.
{URL-encoded-resourceURI}	Gemener URL-kodning för URI:n för gemener
{policyName}	Namnet på den princip för delad åtkomst som denna token refererar till. Saknas om token refererar till autentiseringsuppgifter för enhetsregistret.

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

Node.js

Följande kod genererar en SAS-token med hjälp av resurs-URI, signeringsnyckel, principnamn och förfalloperiod. I nästa avsnitt beskrivs hur du initierar de olika indata för de olika tokenanvändningsfallen.

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', Buffer.from(signingKey, 'base64'));
    hmac.update(toSign);
    var base64UriEncoded = encodeURIComponent(hmac.digest('base64'));

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

Python

Följande kod genererar en SAS-token med hjälp av resurs-URI, signeringsnyckel, principnamn och förfalloperiod. I nästa avsnitt beskrivs hur du initierar de olika indata för de olika tokenanvändningsfallen.

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

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

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

    if policy_name is not None:
        rawtoken['skn'] = policy_name

    return 'SharedAccessSignature ' + parse.urlencode(rawtoken)

C#

Följande kod genererar en SAS-token med hjälp av resurs-URI, signeringsnyckel, principnamn och förfalloperiod. I nästa avsnitt beskrivs hur du initierar de olika indata för de olika tokenanvändningsfallen.

using System;
using System.Globalization;
using System.Net;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;

public static string GenerateSasToken(string resourceUri, string key, string policyName, int expiryInSeconds = 3600)
{
    TimeSpan fromEpochStart = DateTime.UtcNow - new DateTime(1970, 1, 1);
    string expiry = Convert.ToString((int)fromEpochStart.TotalSeconds + expiryInSeconds);

    string stringToSign = WebUtility.UrlEncode(resourceUri) + "\n" + expiry;

    HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(key));
    string signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign)));

    string token = String.Format(CultureInfo.InvariantCulture, "SharedAccessSignature sr={0}&sig={1}&se={2}", WebUtility.UrlEncode(resourceUri), WebUtility.UrlEncode(signature), expiry);

    if (!String.IsNullOrEmpty(policyName))
    {
        token += "&skn=" + policyName;
    }

    return token;
}

Java

Följande kod genererar en SAS-token med hjälp av resurs-URI:n och signeringsnyckeln. Förfalloperioden är inställd på en timme från den aktuella tiden. I nästa avsnitt beskrivs hur du initierar de olika indata för de olika tokenanvändningsfallen.

public static String generateSasToken(String resourceUri, String key) throws Exception {
    // Token will expire in one hour
    var expiry = Instant.now().getEpochSecond() + 3600;

    String stringToSign = URLEncoder.encode(resourceUri, StandardCharsets.UTF_8) + "\n" + expiry;
    byte[] decodedKey = Base64.getDecoder().decode(key);

    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(decodedKey, "HmacSHA256");
    sha256HMAC.init(secretKey);
    Base64.Encoder encoder = Base64.getEncoder();

    String signature = new String(encoder.encode(
        sha256HMAC.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8))), StandardCharsets.UTF_8);

    String token = "SharedAccessSignature sr=" + URLEncoder.encode(resourceUri, StandardCharsets.UTF_8)
            + "&sig=" + URLEncoder.encode(signature, StandardCharsets.UTF_8.name()) + "&se=" + expiry;
            
    return token;
}

Protokollspecifika

Varje protokoll som stöds, till exempel MQTT, AMQP och HTTPS, transporterar token på olika sätt.

När du använder MQTT har CONNECT-paketet deviceId som ClientId, {iothubhostname}/{deviceId} i fältet Användarnamn och en SAS-token i fältet Lösenord. {iothubhostname} ska vara det fullständiga CName för IoT-hubben (till exempel myhub.azure-devices.net).

När du använder AMQP stöder IoT Hub SASL PLAIN och AMQP Claims-Based-Security.

Om du använder AMQP-anspråksbaserad säkerhet anger standarden hur dessa token ska överföras.

För SASL PLAIN kan användarnamnet vara:

• {policyName}@sas.root.{iothubName} om du använder token på IoT-hubbnivå.
• {deviceId}@sas.{iothubname} om du använder token med enhetsomfattning.

I båda fallen innehåller lösenordsfältet token, enligt beskrivningen i SAS-tokenstrukturen.

HTTPS implementerar autentisering genom att inkludera en giltig token i rubriken auktoriseringsbegäran .

Användarnamn (DeviceId är skiftlägeskänsligt): iothubname.azure-devices.net/DeviceId

Lösenord (Du kan generera en SAS-token med CLI-tilläggskommandot az iot hub generate-sas-token eller Azure IoT Hub-tillägget för Visual Studio Code):

SharedAccessSignature sr=iothubname.azure-devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501

Kommentar

Azure IoT SDK:er genererar automatiskt token när du ansluter till tjänsten. I vissa fall stöder Inte Azure IoT SDK:er alla protokoll eller alla autentiseringsmetoder.

Särskilda överväganden för SASL PLAIN

När du använder SASL PLAIN med AMQP kan en klient som ansluter till en IoT-hubb använda en enda token för varje TCP-anslutning. När token upphör att gälla kopplar TCP-anslutningen från tjänsten och utlöser en återanslutning. Det här beteendet, även om det inte är problematiskt för en serverdelsapp, är skadligt för en enhetsapp av följande skäl:

• Gatewayer ansluter vanligtvis för många enheters räkning. När du använder SASL PLAIN måste de skapa en distinkt TCP-anslutning för varje enhet som ansluter till en IoT-hubb. Det här scenariot ökar avsevärt förbrukningen av energi- och nätverksresurser och ökar svarstiden för varje enhetsanslutning.

• Resursbegränsade enheter påverkas negativt av den ökade användningen av resurser för att återansluta efter varje tokens förfallodatum.

Nästa steg

Nu när du har lärt dig hur du styr åtkomsten till IoT Hub kan du vara intresserad av följande avsnitt i utvecklarguiden för IoT Hub:

• Använda enhetstvillingar för att synkronisera tillstånd och konfigurationer
• Anropa en direktmetod på en enhet
• Schemalägga jobb på flera enheter