Kontrolowanie dostępu do usługi Azure IoT Hub Device Provisioning Service (DPS) przy użyciu sygnatur dostępu współdzielonego i tokenów zabezpieczających

Artykuł
03/18/2023

W tym artykule opisano dostępne opcje zabezpieczania usługi Azure IoT Hub Device Provisioning Service (DPS). Usługa aprowizacji używa uwierzytelniania i uprawnień w celu udzielenia dostępu do każdego punktu końcowego. Uprawnienia umożliwiają procesowi uwierzytelniania ograniczenie dostępu do wystąpienia usługi na podstawie funkcji.

W tym artykule omówiono następujące zagadnienia:

Proces uwierzytelniania i tokeny używane przez usługę aprowizacji do weryfikowania uprawnień zarówno względem interfejsów API REST usługi, jak i urządzenia.
Różne uprawnienia, które można udzielić aplikacji zaplecza w celu uzyskania dostępu do interfejsu API usługi.

Uwierzytelnianie

Interfejs API urządzeń obsługuje uwierzytelnianie urządzeń oparte na kluczach i certyfikatach X.509.

Interfejs API usługi obsługuje uwierzytelnianie oparte na kluczach dla aplikacji zaplecza.

W przypadku korzystania z uwierzytelniania opartego na kluczach usługa Device Provisioning Service używa tokenów zabezpieczających do uwierzytelniania usług, aby uniknąć wysyłania kluczy w sieci. Ponadto tokeny zabezpieczające są ograniczone w czasie ważności i zakresie. Zestawy SDK aprowizacji urządzeń usługi Azure IoT automatycznie generują tokeny bez konieczności specjalnej konfiguracji.

W niektórych przypadkach może być konieczne bezpośrednie użycie interfejsów API REST usługi HTTP Device Provisioning Service bez korzystania z zestawów SDK. W poniższych sekcjach opisano sposób uwierzytelniania bezpośrednio względem interfejsów API REST.

Uwierzytelnianie interfejsu API urządzenia

Interfejs API urządzenia jest używany przez urządzenia do zaświadczania o usłudze Device Provisioning i odbierania połączenia usługi IoT Hub.

Uwaga

Aby móc odbierać uwierzytelnione połączenie, urządzenia muszą najpierw być zarejestrowane w usłudze Device Provisioning Service za pośrednictwem rejestracji. Użyj interfejsu API usługi, aby programowo zarejestrować urządzenie za pośrednictwem rejestracji.

Urządzenie musi uwierzytelniać się w interfejsie API urządzenia w ramach procesu aprowizacji. Metoda używana przez urządzenie do uwierzytelniania jest definiowana podczas konfigurowania grupy rejestracji lub rejestracji indywidualnej. Niezależnie od metody uwierzytelniania urządzenie musi wydać adres HTTPS PUT do następującego adresu URL, aby aprowizować się.

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

W przypadku korzystania z uwierzytelniania opartego na kluczach token zabezpieczający jest przekazywany w nagłówku żądania autoryzacji HTTP w następującym formacie:

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

Struktura tokenów zabezpieczających na potrzeby uwierzytelniania opartego na kluczach

Token zabezpieczający jest przekazywany w nagłówku żądania autoryzacji HTTP w następującym formacie:

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

Oczekiwane wartości to:

Wartość	Opis
`{signature}`	Ciąg podpisu HMAC-SHA256 formularza: `{URL-encoded-resourceURI} + "\n" + expiry`. Ważne: Klucz jest dekodowany z base64 i używany jako klucz do wykonywania obliczeń HMAC-SHA256.
`{expiry}`	Ciągi UTF8 dla liczby sekund od epoki 00:00:00 UTC 1 stycznia 1970 r.
`{URL-encoded-resourceURI}`	Kodowanie adresów URL małych liter `{ID_Scope}/registrations/{registration_id}`
`{policyName}`	W przypadku interfejsu API urządzeń te zasady są zawsze "rejestracja".

Poniższy fragment kodu języka Python przedstawia funkcję o nazwie generate_sas_token , która oblicza token z danych wejściowych uri, key, policy_nameexpiry dla rejestracji indywidualnej przy użyciu typu uwierzytelniania klucza symetrycznego.


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

Wynik powinien przypominać następujące dane wyjściowe:


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

W poniższym przykładzie pokazano, jak sygnatura dostępu współdzielonego jest następnie używana do uwierzytelniania za pomocą interfejsu API urządzenia.


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

W przypadku korzystania z symetrycznej grupy rejestracji opartej na kluczach należy najpierw wygenerować device symmetric klucz przy użyciu klucza grupy rejestracji. Użyj podstawowego lub pomocniczego klucza grupy rejestracji, aby obliczyć HMAC-SHA256 identyfikatora rejestracji dla urządzenia. Wynik jest następnie konwertowany na format Base64 w celu uzyskania pochodnego klucza urządzenia. Aby wyświetlić przykłady kodu, zobacz Jak aprowizować urządzenia przy użyciu symetrycznych grup rejestracji kluczy. Po utworzeniu klucza symetrycznego urządzenia możesz zarejestrować urządzenie przy użyciu poprzednich przykładów.

Ostrzeżenie

Aby uniknąć dołączania klucza głównego grupy w kodzie urządzenia, należy wyłączyć proces wyprowadzania klucza urządzenia.

Uwierzytelnianie oparte na certyfikatach

Jeśli skonfigurowano indywidualną rejestrację lub grupę rejestracji na potrzeby uwierzytelniania opartego na certyfikatach X.509, urządzenie będzie musiało użyć wystawionego certyfikatu X.509, aby potwierdzić interfejs API urządzenia. Zapoznaj się z następującymi artykułami dotyczącymi konfigurowania rejestracji i generowania certyfikatu urządzenia.

Szybki start — aprowizuj symulowane urządzenie X.509 w usłudze Azure IoT Hub
Szybki start — rejestrowanie urządzeń X.509 w usłudze Azure Device Provisioning

Po skonfigurowaniu rejestracji i wystawieniu certyfikatu urządzenia w poniższym przykładzie pokazano, jak uwierzytelniać się w interfejsie API urządzenia przy użyciu certyfikatu X.509 urządzenia.


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

Uwierzytelnianie interfejsu API usługi

Interfejs API usługi służy do pobierania stanu rejestracji i usuwania rejestracji urządzeń. Usługa jest również używana przez aplikacje zaplecza do programowego zarządzania grupami i grupami rejestracji. Interfejs API usługi obsługuje uwierzytelnianie oparte na kluczach dla aplikacji zaplecza.

Aby uzyskać dostęp do dowolnego punktu końcowego interfejsu API usługi, musisz mieć odpowiednie uprawnienia. Na przykład aplikacja zaplecza musi zawierać token zawierający poświadczenia zabezpieczeń wraz z każdym komunikatem wysyłanym do usługi.

Usługa Azure IoT Hub Device Provisioning udziela dostępu do punktów końcowych, weryfikując token względem zasad dostępu współdzielonego. Poświadczenia zabezpieczeń, takie jak klucze symetryczne, nigdy nie są wysyłane za pośrednictwem przewodu.

Kontrola dostępu i uprawnienia

Uprawnienia można przyznać w następujący sposób:

Zasady autoryzacji dostępu współdzielonego. Zasady dostępu współdzielonego mogą udzielać dowolnej kombinacji uprawnień. Zasady można definiować w witrynie Azure Portal lub programowo przy użyciu interfejsów API REST usługi Device Provisioning Service. Nowo utworzona usługa aprowizacji ma następujące zasady domyślne:
provisioningserviceowner: zasady ze wszystkimi uprawnieniami. Zobacz uprawnienia, aby uzyskać szczegółowe informacje.

Uwaga

Dostawca zasobów usługi Device Provisioning Service jest zabezpieczony za pośrednictwem subskrypcji platformy Azure, podobnie jak wszyscy dostawcy w usłudze Azure Resource Manager.

Aby uzyskać więcej informacji na temat tworzenia i używania tokenów zabezpieczających, zobacz następną sekcję.

Protokół HTTP jest jedynym obsługiwanym protokołem i implementuje uwierzytelnianie przez dołączenie prawidłowego tokenu w nagłówku żądania autoryzacji .

Przykład

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

Uwaga

Zestawy SDK usługi Azure IoT Device Provisioning automatycznie generują tokeny podczas nawiązywania połączenia z usługą.

Tokeny zabezpieczające

Usługa Device Provisioning Service używa tokenów zabezpieczających do uwierzytelniania usług w celu uniknięcia wysyłania kluczy w sieci. Ponadto tokeny zabezpieczające są ograniczone w czasie ważności i zakresie. Zestawy SDK usługi Azure IoT Device Provisioning automatycznie generują tokeny bez konieczności specjalnej konfiguracji. Niektóre scenariusze wymagają bezpośredniego generowania i używania tokenów zabezpieczających. Takie scenariusze obejmują bezpośrednie użycie powierzchni HTTP.

Struktura tokenu zabezpieczającego

Tokeny zabezpieczające służą do udzielania ograniczonego czasowo dostępu usług do określonych funkcji w usłudze IoT Device Provisioning Service. Aby uzyskać autoryzację w celu nawiązania połączenia z usługą aprowizacji, usługi muszą wysyłać tokeny zabezpieczające podpisane przy użyciu dostępu współdzielonego lub klucza symetrycznego.

Token podpisany przy użyciu klucza dostępu współdzielonego udziela dostępu do wszystkich funkcji skojarzonych z uprawnieniami zasad dostępu współdzielonego.

Token zabezpieczający ma następujący format:

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

Poniżej przedstawiono oczekiwane wartości

Wartość	Opis
{signature}	Ciąg podpisu HMAC-SHA256 formularza: `{URL-encoded-resourceURI} + "\n" + expiry`. Ważne: Klucz jest dekodowany z base64 i używany jako klucz do wykonywania obliczeń HMAC-SHA256.
{wygaśnięcie}	Ciągi UTF8 dla liczby sekund od epoki 00:00:00 UTC 1 stycznia 1970 r.
{Identyfikator URL zakodowany zasób}	Małe litery kodowanie adresów URL identyfikatora URI zasobu małego liter. Prefiks identyfikatora URI (według segmentu) punktów końcowych, do których można uzyskać dostęp za pomocą tego tokenu, począwszy od nazwy hosta usługi IoT Device Provisioning Service (bez protokołu). Na przykład `mydps.azure-devices-provisioning.net`.
{policyName}	Nazwa zasad dostępu współdzielonego, do których odwołuje się ten token.

Uwaga

Prefiks identyfikatora URI jest obliczany według segmentu, a nie według znaku. Na przykład /a/b jest prefiksem , /a/b/c ale nie dla /a/bc.

Poniższy fragment kodu Node.js przedstawia funkcję o nazwie generateSasToken , która oblicza token z danych wejściowych resourceUri, signingKey, policyName, expiresInMins. W następnych sekcjach opisano sposób inicjowania różnych danych wejściowych dla różnych przypadków użycia tokenu.

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

Dla porównania równoważny kod języka Python do wygenerowania tokenu zabezpieczającego to:

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)

Uwaga

Ponieważ czas ważności tokenu jest weryfikowany na maszynach usługi IoT Device Provisioning Service, dryf na zegarze maszyny, która generuje token, musi być minimalny.

Używanie tokenów zabezpieczających ze składników usługi

Składniki usługi mogą generować tokeny zabezpieczające tylko przy użyciu zasad dostępu współdzielonego, udzielając odpowiednich uprawnień, jak wyjaśniono wcześniej.

Oto funkcje usługi uwidocznione w punktach końcowych:

Punkt końcowy	Funkcje
`{your-service}.azure-devices-provisioning.net/enrollments`	Udostępnia operacje rejestracji urządzeń w usłudze Device Provisioning Service.
`{your-service}.azure-devices-provisioning.net/enrollmentGroups`	Udostępnia operacje zarządzania grupami rejestracji urządzeń.
`{your-service}.azure-devices-provisioning.net/registrations/{id}`	Udostępnia operacje pobierania stanu rejestracji urządzeń i zarządzania nimi.

Na przykład usługa wygenerowana przy użyciu wstępnie utworzonych zasad dostępu współdzielonego o nazwie enrollmentread tworzy token z następującymi parametrami:

identyfikator URI zasobu: {mydps}.azure-devices-provisioning.net,
klucz podpisywania: jeden z kluczy enrollmentread zasad,
nazwa zasad: enrollmentread,
dowolny czas wygaśnięcia.backn

Create a shared access policy for your Device Provisioning Service instance in the portal

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

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

Wynikiem, który przyzna dostęp do odczytu wszystkich rekordów rejestracji, będzie:

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

Zestawy SDK i przykłady

Tematy referencyjne:

Poniższe tematy referencyjne zawierają więcej informacji na temat kontrolowania dostępu do usługi IoT Device Provisioning.

Uprawnienia usługi Device Provisioning Service

W poniższej tabeli wymieniono uprawnienia, których można użyć do kontrolowania dostępu do usługi IoT Device Provisioning Service.

Uprawnienie	Uwagi
Serviceconfig	Udziela dostępu w celu zmiany konfiguracji usługi. To uprawnienie jest używane przez usługi w chmurze zaplecza.
EnrollmentRead	Przyznaje dostęp do odczytu do rejestracji urządzeń i grup rejestracji. To uprawnienie jest używane przez usługi w chmurze zaplecza.
RejestracjaWrite	Przyznaje dostęp do zapisu do rejestracji urządzeń i grup rejestracji. To uprawnienie jest używane przez usługi w chmurze zaplecza.
RegistrationStatusRead	Przyznaje dostęp do odczytu do stanu rejestracji urządzenia. To uprawnienie jest używane przez usługi w chmurze zaplecza.
RegistrationStatusWrite	Umożliwia usunięcie dostępu do stanu rejestracji urządzenia. To uprawnienie jest używane przez usługi w chmurze zaplecza.

Kontrolowanie dostępu do usługi Azure IoT Hub Device Provisioning Service (DPS) przy użyciu sygnatur dostępu współdzielonego i tokenów zabezpieczających

Uwierzytelnianie

Uwierzytelnianie interfejsu API urządzenia

Struktura tokenów zabezpieczających na potrzeby uwierzytelniania opartego na kluczach

Uwierzytelnianie oparte na certyfikatach

Uwierzytelnianie interfejsu API usługi

Kontrola dostępu i uprawnienia

Przykład

Tokeny zabezpieczające

Struktura tokenu zabezpieczającego

Używanie tokenów zabezpieczających ze składników usługi

Zestawy SDK i przykłady

Tematy referencyjne:

Uprawnienia usługi Device Provisioning Service

Dodatkowe zasoby