Aracılığıyla paylaş

Control access to Azure IoT Hub Device Provisioning Service (DPS) with shared access signatures and security tokens

This article describes the available options for securing your Azure IoT Hub Device Provisioning Service (DPS). The provisioning service uses authentication and permissions to grant access to each endpoint. Permissions allow the authentication process to limit access to a service instance based on functionality.

This article discusses:

  • The authentication process and the tokens the provisioning service uses to verify permissions against both the Service and Device REST APIs.

  • The different permissions that you can grant to a backend app to access the Service API.

Kimlik doğrulama

Cihaz API'si anahtar tabanlı ve X.509 sertifika tabanlı cihaz kimlik doğrulamasını destekler.

Hizmet API'si arka uç uygulamaları için anahtar tabanlı kimlik doğrulamasını destekler.

Anahtar tabanlı kimlik doğrulamasını kullanırken Cihaz Sağlama Hizmeti, anahtar göndermeyi önlemek amacıyla hizmetlerin kimliğini doğrulamak için güvenlik belirteçlerini kullanır. Ayrıca, güvenlik belirteçleri zaman geçerliliği ve kapsamı sınırlıdır. Azure IoT Device Provisioning SDKs automatically generate tokens without requiring any special configuration.

Bazı durumlarda SDK'ları kullanmadan DOĞRUDAN HTTP Cihaz Sağlama Hizmeti REST API'lerini kullanmanız gerekebilir. Aşağıdaki bölümlerde REST API'lerinde doğrudan kimlik doğrulamasının nasıl yapılacağını açıklanmaktadır.

Cihaz API'sinde kimlik doğrulaması

The Device API is used by devices to attest to the Device Provisioning Service and receive an IoT Hub connection.

Uyarı

Kimliği doğrulanmış bir bağlantı almak için cihazların önce bir kayıt aracılığıyla Cihaz Sağlama Hizmeti'ne kaydedilmesi gerekir. Bir cihazı bir kaydolma işlemi üzerinden programlama yoluyla kaydetmek için Servis API'sini kullanın.

Bir cihazın, sağlama işleminin bir parçası olarak Cihaz API'sinde kimlik doğrulaması yapması gerekir. Bir cihazın kimlik doğrulaması için kullandığı yöntem, bir kayıt grubu veya bireysel kayıt ayarladığınızda tanımlanır. Kimlik doğrulama yöntemi ne olursa olsun, cihazın kendisini sağlamak için aşağıdaki URL'ye bir HTTPS PUT vermesi gerekir.

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

If using key-based authentication, a security token is passed in the HTTP Authorization request header in the following format:

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

Anahtar tabanlı kimlik doğrulaması için güvenlik belirteci yapısı

The security token is passed in the HTTP Authorization request header in the following format:

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

Beklenen değerler şunlardır:

Value Açıklama
{signature} An HMAC-SHA256 signature string of the form: {URL-encoded-resourceURI} + "\n" + expiry.  Important: The key is decoded from base64 and used as key to do the HMAC-SHA256 computation.
{expiry} UTF8 strings for number of seconds since the epoch 00:00:00 UTC on 1 January 1970.
{URL-encoded-resourceURI} Lower case URL-encoding of {ID_Scope}/registrations/{registration_id}
{policyName} For the Device API, this policy is always “registration”.

Aşağıdaki Python kod parçacığı, simetrik anahtar kimlik doğrulama türü kullanarak tek bir kayıt için generate_sas_token, uri, keypolicy_name girişlerinden belirteci hesaplayan expiry adlı bir işlevi gösterir.


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

Sonuç aşağıdaki çıkışa benzemelidir:


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

Aşağıdaki örnekte, paylaşılan erişim imzasının Cihaz API'siyle kimlik doğrulaması yapmak için nasıl kullanıldığı gösterilmektedir.


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

If using a symmetric key-based enrollment group, you'll need to first generate a device symmetric key using the enrollment group key. Use the enrollment group primary or secondary key to compute an HMAC-SHA256 of the registration ID for the device. Sonuç daha sonra türetilmiş cihaz anahtarını almak için Base64 biçimine dönüştürülür. To view code examples, see How to provision devices using symmetric key enrollment groups. Once the device symmetric key has been derived, you can register the device using the previous examples.

Uyarı

To avoid including the group master key in your device code, the process of deriving device key should be done off the device.

Sertifika tabanlı kimlik doğrulaması

If you've set up an individual enrollment or enrollment group for X.509 certificated-based authentication, the device will need to use its issued X.509 certificate to attest to Device API. Kaydı ayarlama ve cihaz sertifikası oluşturma hakkında aşağıdaki makalelere bakın.

Once the enrollment has been set up and the device certificate issued, the following example demonstrates how to authenticate to Device API with the device’s X.509 certificate.


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

Hizmet API'sinde kimlik doğrulaması

The Service API is used to retrieve registration state and remove device registrations. The service is also used by backend apps to programmatically manage both individual groups and enrollment groups. Hizmet API'si arka uç uygulamaları için anahtar tabanlı kimlik doğrulamasını destekler.

Hizmet API'sinin uç noktalarına erişmek için uygun izinlere sahip olmanız gerekir. Örneğin, bir arka uç uygulaması hizmete gönderdiği her iletiyle birlikte güvenlik kimlik bilgilerini içeren bir belirteç içermelidir.

Azure IoT Hub Device Provisioning Service grants access to endpoints by verifying the token against the shared access policies. Simetrik anahtarlar gibi güvenlik kimlik bilgileri hiçbir zaman kablo üzerinden gönderilmez.

Erişim denetimi ve izinler

You can grant permissions in the following ways:

  • Shared access authorization policies. Shared access policies can grant any combination of permissions. You can define policies in the Azure portal, or programmatically by using the Device Provisioning Service REST APIs. A newly created provisioning service has the following default policy:

  • provisioningserviceowner: Policy with all permissions. See permissions for detailed information.

Uyarı

The Device Provisioning Service resource provider is secured through your Azure subscription, as are all providers in the Azure Resource Manager.

For more information about how to construct and use security tokens, see the next section.

HTTP is the only supported protocol, and it implements authentication by including a valid token in the Authorization request header.

Örnek

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

Uyarı

The Azure IoT Device Provisioning Service SDKs automatically generate tokens when connecting to the service.

Güvenlik belirteçleri

Cihaz Sağlama Hizmeti, anahtarların kabloya gönderilmesini önlemek için hizmetlerin kimliğini doğrulamak için güvenlik belirteçlerini kullanır. Ayrıca, güvenlik belirteçleri zaman geçerliliği ve kapsamı sınırlıdır. Azure IoT Device Provisioning Service SDKs automatically generate tokens without requiring any special configuration. Bazı senaryolar doğrudan güvenlik belirteçleri oluşturmanızı ve kullanmanızı gerektirir. Bu tür senaryolar HTTP yüzeyinin doğrudan kullanımını içerir.

Güvenlik belirteci yapısı

You use security tokens to grant time-bounded access for services to specific functionality in IoT Device Provisioning Service. Sağlama hizmetine bağlanmak için yetkilendirme almak için hizmetlerin paylaşılan erişim veya simetrik anahtarla imzalanan güvenlik belirteçleri göndermesi gerekir.

Paylaşılan erişim anahtarıyla imzalanan belirteç, paylaşılan erişim ilkesi izinleri ile ilişkili tüm işlevlere erişim verir.

Güvenlik belirteci aşağıdaki biçime sahiptir:

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

Here are the expected values

Value Açıklama
{signature} An HMAC-SHA256 signature string of the form: {URL-encoded-resourceURI} + "\n" + expiry. Important: The key is decoded from base64 and used as key to do the HMAC-SHA256 computation.
{geçerlilik süresi} UTF8 strings for number of seconds since the epoch 00:00:00 UTC on 1 January 1970.
{URL-encoded-resourceURI} Lower case URL-encoding of the lower case resource URI. URI prefix (by segment) of the endpoints that can be accessed with this token, starting with host name of the IoT Device Provisioning Service (no protocol). Örneğin, mydps.azure-devices-provisioning.net.
{policyName} The name of the shared access policy to which this token refers.

Uyarı

URI ön eki karaktere göre değil segmente göre hesaplanır. Örneğin /a/b/a/b/c için bir ön ektir ancak /a/bciçin değildir.

Aşağıdaki Node.js kod parçacığı, girişlerinden belirteci hesaplayan resourceUri, signingKey, policyName, expiresInMins adlı bir işlevi gösterir. Sonraki bölümlerde, farklı belirteç kullanım durumları için farklı girişlerin nasıl başlatılacağı detaylandırılmaktadır.

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

Karşılaştırma olarak, bir güvenlik belirteci oluşturmak için eşdeğer Python kodu şunlardır:

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)

Uyarı

Since the time validity of the token is validated on IoT Device Provisioning Service machines, the drift on the clock of the machine that generates the token must be minimal.

Hizmet bileşenlerinden güvenlik belirteçlerini kullanma

Hizmet bileşenleri yalnızca daha önce açıklandığı gibi uygun izinleri veren paylaşılan erişim ilkelerini kullanarak güvenlik belirteçleri oluşturabilir.

Here are the service functions exposed on the endpoints:

Bitiş noktası İşlevsellik
{your-service}.azure-devices-provisioning.net/enrollments Cihaz Sağlama Hizmeti ile cihaz kayıt işlemleri sağlar.
{your-service}.azure-devices-provisioning.net/enrollmentGroups Cihaz kayıt gruplarını yönetmeye yönelik işlemler sağlar.
{your-service}.azure-devices-provisioning.net/registrations/{id} Cihaz kayıtlarının durumunu almak ve yönetmek için işlemler sağlar.

As an example, a service generated using a pre-created shared access policy called enrollmentread would create a token with the following parameters:

  • kaynak URI'si: {mydps}.azure-devices-provisioning.net,
  • imzalama anahtarı: enrollmentread ilkesinin anahtarlarından biri,
  • ilke adı: enrollmentread,
  • any expiration time.backn
var endpoint ="mydps.azure-devices-provisioning.net";
var policyName = 'enrollmentread'; 
var policyKey = '...';

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

Tüm kayıt kayıtlarını okumak için erişim izni veren sonuç şu şekilde olacaktır:

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

SDKs and samples

Reference topics:

The following reference topics provide you with more information about controlling access to your IoT Device Provisioning Service.

Cihaz Sağlama Hizmeti izinleri

The following table lists the permissions you can use to control access to your IoT Device Provisioning Service.

İzin Notes
ServiceConfig Hizmet yapılandırmalarını değiştirmek için erişim verir.
Bu izin arka uç bulut hizmetleri tarafından kullanılır.
EnrollmentRead Grants read access to the device enrollments and enrollment groups.
Bu izin arka uç bulut hizmetleri tarafından kullanılır.
EnrollmentWrite Grants write access to the device enrollments and enrollment groups.
Bu izin arka uç bulut hizmetleri tarafından kullanılır.
RegistrationStatusRead Cihaz kayıt durumuna okuma erişimi verir.
Bu izin arka uç bulut hizmetleri tarafından kullanılır.
RegistrationStatusWrite Cihaz kayıt durumuna silme erişimi verir.
Bu izin arka uç bulut hizmetleri tarafından kullanılır.