Steuern des Zugriffs auf den Azure IoT Hub Device Provisioning Service (DPS) mit freigegebenen Zugriffssignaturen und Sicherheitstoken

In diesem Artikel werden die verfügbaren Optionen zum Sichern Ihres Azure IoT Hub Device Provisioning Service (DPS) beschrieben. Der Bereitstellungsdienst verwendet Authentifizierung und Berechtigungen , um jedem Endpunkt Zugriff zu gewähren. Berechtigungen ermöglichen es dem Authentifizierungsprozess, den Zugriff auf eine Dienstinstanz basierend auf der Funktionalität einzuschränken.

In diesem Artikel wird Folgendes erläutert:

• Der Authentifizierungsprozess und die Token, die der Bereitstellungsdienst verwendet, um Berechtigungen für die DIENST- und Geräte-REST-APIs zu überprüfen.

• Die verschiedenen Berechtigungen, die Sie einer Back-End-App für den Zugriff auf die Dienst-API gewähren können.

Authentifizierung

Die Geräte-API unterstützt die schlüsselbasierte und die zertifikatbasierte X.509-Geräteauthentifizierung.

Die Dienst-API unterstützt die schlüsselbasierte Authentifizierung für Back-End-Apps.

Bei verwendung der schlüsselbasierten Authentifizierung verwendet der Gerätebereitstellungsdienst Sicherheitstoken zum Authentifizieren von Diensten, um das Senden von Schlüsseln über das Kabel zu vermeiden. Darüber hinaus sind Sicherheitstoken in Zeitlicher Gültigkeit und Umfang begrenzt. Azure IoT Hub Device Provisioning SDKs generieren automatisch Token, ohne dass eine spezielle Konfiguration erforderlich ist.

In einigen Fällen müssen Sie möglicherweise die REST-APIs des HTTP-Bereitstellungsdiensts direkt verwenden, ohne die SDKs zu verwenden. In den folgenden Abschnitten wird beschrieben, wie Sie sich direkt bei den REST-APIs authentifizieren.

Geräte-API-Authentifizierung

Die Geräte-API wird von Geräten verwendet, um den Gerätebereitstellungsdienst zu bestätigen und eine IoT Hub-Verbindung zu erhalten.

Ein Gerät muss sich im Rahmen des Bereitstellungsprozesses bei der Geräte-API authentifizieren. Die Methode, die ein Gerät zur Authentifizierung verwendet, wird definiert, wenn Sie eine Registrierungsgruppe oder einzelne Registrierung einrichten. Unabhängig von der Authentifizierungsmethode muss das Gerät einen HTTPS PUT an die folgende URL ausgeben, um sich selbst bereitzustellen.

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

Bei Verwendung der schlüsselbasierten Authentifizierung wird ein Sicherheitstoken im HTTP-Autorisierungsanforderungsheader im folgenden Format übergeben:

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

Sicherheitstokenstruktur für die schlüsselbasierte Authentifizierung

Das Sicherheitstoken wird im HTTP-Autorisierungsanforderungsheader im folgenden Format übergeben:

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

Die erwarteten Werte sind:

Der folgende Python-Codeausschnitt zeigt eine Funktion namens generate_sas_token, die das Token aus den Eingaben uri, key, policy_name, expiry für eine einzelne Registrierung durch Authentifizierung mit einem symmetrischen Schlüssel berechnet.

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

Das Ergebnis sollte der folgenden Ausgabe ähneln:

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

Das folgende Beispiel zeigt, wie die Signatur für den freigegebenen Zugriff dann zur Authentifizierung mit der Geräte-API verwendet wird.

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 

Wenn Sie eine symmetrische schlüsselbasierte Registrierungsgruppe verwenden, müssen Sie zunächst einen device symmetric Schlüssel mithilfe des Registrierungsgruppenschlüssels generieren. Verwenden Sie den primären oder sekundären Schlüssel der Registrierungsgruppe, um eine HMAC-SHA256 der Registrierungs-ID für das Gerät zu berechnen. Das Ergebnis wird dann in das Base64-Format konvertiert, um den abgeleiteten Geräteschlüssel abzurufen. Informationen zum Anzeigen von Codebeispielen finden Sie unter "Ableiten eines Geräteschlüssels". Nachdem der symmetrische Geräteschlüssel abgeleitet wurde, können Sie das Gerät mithilfe der vorherigen Beispiele registrieren.

Zertifikatbasierte Authentifizierung

Wenn Sie eine einzelne Registrierungs- oder Registrierungsgruppe für die zertifikatbasierte X.509-Authentifizierung einrichten, muss das Gerät sein ausgestelltes X.509-Zertifikat verwenden, um die Geräte-API zu bestätigen. In den folgenden Artikeln erfahren Sie, wie Sie die Registrierung einrichten und das Gerätezertifikat generieren.

• Schnellstart: Einrichtung eines simulierten Geräts mit X.509-Zertifikat

• Programmgesteuertes Erstellen einer Gerätebereitstellungsdienst-Registrierungsgruppe für den X.509-Zertifikatnachweis

Nachdem die Registrierung eingerichtet und das ausgestellte Gerätezertifikat ausgestellt wurde, veranschaulicht das folgende Beispiel, wie sie sich bei der Geräte-API mit dem X.509-Zertifikat des Geräts authentifizieren.

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 

Dienst-API-Authentifizierung

Die Dienst-API wird verwendet, um den Registrierungsstatus abzurufen und Geräteregistrierungen zu entfernen. Der Dienst wird auch von Back-End-Apps verwendet, um sowohl einzelne Gruppen als auch Registrierungsgruppen programmgesteuert zu verwalten. Die Dienst-API unterstützt die schlüsselbasierte Authentifizierung für Back-End-Apps.

Sie müssen über entsprechende Berechtigungen verfügen, um auf einen der Dienst-API-Endpunkte zuzugreifen. Beispielsweise muss eine Back-End-App ein Token mit Sicherheitsanmeldeinformationen zusammen mit jeder Nachricht enthalten, die sie an den Dienst sendet.

Azure IoT Hub Device Provisioning Service gewährt Endpunkten Zugriff, indem das Token anhand der Richtlinien für den gemeinsamen Zugriff überprüft wird. Sicherheitsanmeldeinformationen, z. B. symmetrische Schlüssel, werden nie über das Kabel gesendet.

Zugriffssteuerung und -berechtigungen

Sie können Berechtigungen auf folgende Weise erteilen:

• Autorisierungsrichtlinien für den freigegebenen Zugriff. Richtlinien für den geteilten Zugriff können beliebige Kombinationen von Berechtigungen gewähren. Sie können Richtlinien im Azure-Portal oder programmgesteuert mithilfe der REST-APIs des Gerätebereitstellungsdiensts definieren. Ein neu erstellter Bereitstellungsdienst verfügt über die folgende Standardrichtlinie:

• provisioningserviceowner: Richtlinie mit sämtlichen Berechtigungen. Detaillierte Informationen finden Sie unter Berechtigungen .

Weitere Informationen zum Erstellen und Verwenden von Sicherheitstoken finden Sie im nächsten Abschnitt.

HTTP ist das einzige unterstützte Protokoll und implementiert die Authentifizierung, indem ein gültiges Token in den Autorisierungsanforderungsheader eingeschlossen wird.

Example

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

Sicherheitstoken

Der Gerätebereitstellungsdienst verwendet Sicherheitstoken zum Authentifizieren von Diensten, um das Senden von Schlüsseln über das Netzwerk zu vermeiden. Darüber hinaus sind Sicherheitstoken in Zeitlicher Gültigkeit und Umfang begrenzt. Azure IoT Hub Device Provisioning Service SDKs generieren automatisch Token, ohne dass eine spezielle Konfiguration erforderlich ist. In einigen Szenarien müssen Sie Sicherheitstoken direkt generieren und verwenden. Solche Szenarien umfassen die direkte Verwendung der HTTP-Oberfläche.

Sicherheitstokenstruktur

Sie verwenden Sicherheitstoken, um zeitgebundenen Zugriff für Dienste auf bestimmte Funktionen im IoT Hub-Gerätebereitstellungsdienst zu gewähren. Um die Autorisierung zum Herstellen einer Verbindung mit dem Bereitstellungsdienst zu erhalten, müssen Dienste Sicherheitstoken senden, die entweder mit einem freigegebenen Zugriff oder einem symmetrischen Schlüssel signiert sind.

Ein token, das mit einem freigegebenen Zugriffsschlüssel signiert ist, gewährt Zugriff auf alle Funktionen, die den Berechtigungen der freigegebenen Zugriffsrichtlinie zugeordnet sind.

Das Sicherheitstoken weist das folgende Format auf:

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

Dies sind die erwarteten Werte.

Der folgende Node.js Codeausschnitt zeigt eine Funktion namens generateSasToken , die das Token aus den Eingaben resourceUri, signingKey, policyName, expiresInMinsberechnet. In den nächsten Abschnitten wird erläutert, wie die verschiedenen Eingaben für die verschiedenen Token-Anwendungsfälle initialisiert werden.

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

Im Vergleich dazu lautet der entsprechende Python-Code zum Generieren eines Sicherheitstokens:

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)

Verwenden von Sicherheitstoken aus Dienstkomponenten

Dienstkomponenten können nur Sicherheitstoken mit freigegebenen Zugriffsrichtlinien generieren, die die entsprechenden Berechtigungen gewähren, wie zuvor erläutert.

Hier sind die Dienstfunktionen, die auf den Endpunkten verfügbar gemacht werden:

Beispielsweise würde ein mit einer vordefinierten Richtlinie enrollmentread für den freigegebenen Zugriff generierter Dienst ein Token mit den folgenden Parametern erstellen:

• Ressourcen-URI: {mydps}.azure-devices-provisioning.net,
• Signaturschlüssel: einer der Schlüssel der enrollmentread Richtlinie,
• Richtlinienname: enrollmentread,
• Eine Ablaufzeit

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

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

Das Ergebnis, das Zugriff auf das Lesen aller Registrierungsdatensätze gewähren würde, wäre:

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

SDKs und Beispiele

• Microsoft Azure IoT SDKs für Java
  • Beispiel
• Microsoft Azure IoT SDK für .NET
  • Beispiel

Referenzartikel:

Die folgenden Referenzartikel enthalten weitere Informationen zum Steuern des Zugriffs auf Ihren IoT-Gerätebereitstellungsdienst.

Berechtigungen des Gerätebereitstellungsdienstes

In der folgenden Tabelle sind die Berechtigungen aufgeführt, die Sie verwenden können, um den Zugriff auf Ihren IoT-Gerätebereitstellungsdienst zu steuern.