Contrôler l’accès au service Azure IoT Hub Device Provisioning (DPS) avec des signatures d’accès partagé et des jetons de sécurité

Cet article décrit les options disponibles pour sécuriser votre service Azure IoT Hub Device Provisioning (DPS). Le service d’approvisionnement utilise l’authentification et les autorisations pour accorder l’accès à chaque point de terminaison. Les autorisations permettent au processus d’authentification de limiter l’accès à une instance de service en fonction des fonctionnalités.

Cet article traite des points suivants :

• Le processus d’authentification et les jetons que le service d’approvisionnement utilise pour vérifier les autorisations sur les API REST du service et de l’appareil.

• Les différentes autorisations que vous pouvez accorder à une application back-end pour accéder à l’API de service.

Authentication

L'API de l'appareil prend en charge l'authentification des appareils à base de clé ainsi que celle à base de certificats X.509.

L’API de service prend en charge l’authentification basée sur des clés pour les applications principales.

Lorsque vous utilisez l’authentification basée sur des clés, le service Device Provisioning utilise des jetons de sécurité pour authentifier les services afin d’éviter d’envoyer des clés sur le câble. En outre, les jetons de sécurité sont limités dans le temps de validité et d’étendue. Les kits SDK Azure IoT Hub Device Provisioning génèrent automatiquement des jetons sans nécessiter de configuration spéciale.

Dans certains cas, vous devrez peut-être utiliser directement les API REST du service Device Provisioning HTTP, sans utiliser les kits SDK. Les sections suivantes décrivent comment s’authentifier directement auprès des API REST.

Authentification de l’API d’appareil

L’API d’appareil est utilisée par les appareils pour attester auprès du service Device Provisioning et recevoir une connexion IoT Hub.

Un appareil doit s’authentifier auprès de l’API d’appareil dans le cadre du processus d’approvisionnement. La méthode utilisée par un appareil pour l’authentification est définie lorsque vous configurez un groupe d’inscription ou une inscription individuelle. Quelle que soit la méthode d’authentification, l’appareil doit envoyer un HTTPS PUT sur l’URL suivante pour se provisionner.

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

Si vous utilisez l’authentification basée sur des clés, un jeton de sécurité est transmis dans l’en-tête de demande d’autorisation HTTP au format suivant :

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

Structure des jetons de sécurité pour l’authentification basée sur des clés

Le jeton de sécurité est passé dans l’en-tête de demande d’autorisation HTTP au format suivant :

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

Les valeurs attendues sont les suivantes :

L'extrait de code Python suivant montre une fonction appelée generate_sas_token qui calcule le jeton à partir des entrées uri, key, policy_name, expiry pour une inscription individuelle à l’aide d’un type d’authentification par clé symétrique.

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

Le résultat doit ressembler à la sortie suivante :

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

L’exemple suivant montre comment la signature d’accès partagé est ensuite utilisée pour s’authentifier auprès de l’API appareil.

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 

Si vous utilisez un groupe d’inscription à clé symétrique, vous devez d’abord générer une device symmetric clé à l’aide de la clé de groupe d’inscription. Utilisez la clé primaire ou secondaire du groupe d’inscription pour calculer un HMAC-SHA256 de l’ID d’inscription de l’appareil. Le résultat est ensuite converti au format Base64 pour obtenir la clé d’appareil dérivée. Pour afficher des exemples de code, consultez Dériver une clé d’appareil. Une fois la clé symétrique de l’appareil dérivée, vous pouvez enregistrer l’appareil en utilisant les exemples précédents.

Authentification basée sur un certificat

Si vous configurez une inscription individuelle ou un groupe d'inscription pour l'authentification basée sur un certificat X.509, l'appareil doit utiliser son certificat X.509 émis pour se présenter à l'API de l'appareil. Reportez-vous aux articles suivants sur la configuration de l’inscription et la génération du certificat d’appareil.

• Guide de démarrage rapide : Configurer un appareil simulé avec certificat X.509

• Créer par programmation un groupe d’inscription du service de provisionnement des appareils pour une attestation de certificat X.509

Une fois l’inscription configurée et le certificat d’appareil émis, l’exemple suivant montre comment s’authentifier auprès de l’API appareil avec le certificat X.509 de l’appareil.

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 

Authentification de l’API de service

L’API de service est utilisée pour récupérer l’état d’inscription et supprimer les inscriptions d’appareils. Le service est également utilisé par les applications principales pour gérer par programme des groupes individuels et des groupes d’inscription. L’API de service prend en charge l’authentification basée sur des clés pour les applications principales.

Vous devez disposer des autorisations appropriées pour accéder à l’un des points de terminaison de l’API de service. Par exemple, une application back-end doit inclure un jeton contenant des informations d’identification de sécurité, ainsi que chaque message qu’il envoie au service.

Le service Azure IoT Hub Device Provisioning accorde l’accès aux points de terminaison en vérifiant le jeton par rapport aux stratégies d’accès partagé. Les informations d’identification de sécurité, telles que les clés symétriques, ne sont jamais envoyées via le câble.

Contrôle d’accès et autorisations

Vous pouvez accorder des autorisations de la manière suivante :

• Stratégies d’autorisation d’accès partagé. Les stratégies d’accès partagé peuvent accorder n’importe quelle combinaison d’autorisations. Vous pouvez définir des stratégies dans le portail Azure ou par programmation à l’aide des API REST du service Device Provisioning. Un service d’approvisionnement nouvellement créé a la stratégie par défaut suivante :

• provisioningserviceowner : stratégie avec toutes les autorisations. Consultez les autorisations pour obtenir des informations détaillées.

Pour plus d’informations sur la construction et l’utilisation des jetons de sécurité, consultez la section suivante.

HTTP est le seul protocole pris en charge et implémente l’authentification en incluant un jeton valide dans l’en-tête de demande d’autorisation .

Example

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

Jetons de sécurité

Le service Device Provisioning utilise des jetons de sécurité pour authentifier les services afin d’éviter d’envoyer des clés sur le réseau. En outre, les jetons de sécurité sont limités dans le temps de validité et d’étendue. Les kits SDK du service Azure IoT Hub Device Provisioning génèrent automatiquement des jetons sans nécessiter de configuration spéciale. Certains scénarios vous obligent à générer et à utiliser des jetons de sécurité directement. Ces scénarios incluent l’utilisation directe de la surface HTTP.

Structure des jetons de sécurité

Vous utilisez des jetons de sécurité pour accorder un accès limité au temps pour les services à des fonctionnalités spécifiques dans le service IoT Hub Device Provisioning. Pour obtenir l’autorisation de se connecter au service d’approvisionnement, les services doivent envoyer des jetons de sécurité signés avec un accès partagé ou une clé symétrique.

Un jeton signé avec une clé d’accès partagé accorde l’accès à toutes les fonctionnalités associées aux autorisations de stratégie d’accès partagé.

Le jeton de sécurité a le format suivant :

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

Voici les valeurs attendues

L’extrait de code Node.js suivant montre une fonction appelée generateSasToken qui calcule le jeton à partir des entrées resourceUri, signingKey, policyName, expiresInMins. Les sections suivantes expliquent comment initialiser les différentes entrées pour les différents cas d’usage de jeton.

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

En comparaison, le code Python équivalent pour générer un jeton de sécurité est :

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)

Utiliser des jetons de sécurité à partir de composants de service

Les composants de service peuvent uniquement générer des jetons de sécurité à l’aide de stratégies d’accès partagé accordant les autorisations appropriées, comme expliqué précédemment.

Voici les fonctions de service exposées sur les points de terminaison :

Par exemple, un service généré à l’aide d’une stratégie d’accès partagé précréée appelée enrollmentread créerait un jeton avec les paramètres suivants :

• URI de ressource : {mydps}.azure-devices-provisioning.net,
• clé de signature : une des clés de la stratégie enrollmentread ,
• nom de stratégie : enrollmentread,
• n’importe quel délai d’expiration time.backn

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

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

Le résultat, qui accorderait l’accès pour lire tous les enregistrements d’inscription, serait :

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

SDK et exemples

• Sdk Microsoft Azure IoT pour Java
  • Exemple
• Kit de développement logiciel (SDK) Microsoft Azure IoT pour .NET
  • Exemple

Articles de référence :

Les articles de référence suivants vous fournissent plus d’informations sur le contrôle de l’accès à votre service IoT Device Provisioning.

Permissions pour le service Device Provisioning

Le tableau suivant répertorie les autorisations que vous pouvez utiliser pour contrôler l’accès à votre service IoT Device Provisioning.