Controllare l'accesso all'hub IoTControl access to IoT Hub

Questo articolo illustra le opzioni per la protezione dell'hub IoT.This article describes the options for securing your IoT hub. L'hub IoT usa le autorizzazioni per concedere l'accesso a ogni endpoint dell'hub stesso.IoT Hub uses permissions to grant access to each IoT hub endpoint. Le autorizzazioni limitano l'accesso a un hub IoT in base alla funzionalità.Permissions limit the access to an IoT hub based on functionality.

L'articolo illustra:This article describes:

  • Le diverse autorizzazioni che è possibile concedere a un'app per dispositivo o back-end per accedere all'hub IoT.The different permissions that you can grant to a device or back-end app to access your IoT hub.
  • Il processo di autenticazione e i token usati per verificare le autorizzazioni.The authentication process and the tokens it uses to verify permissions.
  • Come definire l'ambito delle credenziali per limitare l'accesso a risorse specifiche.How to scope credentials to limit access to specific resources.
  • Supporto dell'hub IoT per i certificati x.509.IoT Hub support for X.509 certificates.
  • Meccanismo di autenticazione personalizzata del dispositivo che usa gli schemi di autenticazione o i registri di identità del dispositivo esistenti.Custom device authentication mechanisms that use existing device identity registries or authentication schemes.

È necessario avere le autorizzazioni appropriate per accedere agli endpoint dell'hub IoT.You must have appropriate permissions to access any of the IoT Hub endpoints. Un dispositivo, ad esempio, deve includere un token contenente le credenziali di sicurezza con ogni messaggio inviato all'hub IoT.For example, a device must include a token containing security credentials along with every message it sends to IoT Hub.

Controllo dell'accesso e autorizzazioniAccess control and permissions

Per concedere le autorizzazioni è possibile procedere nei modi seguenti:You can grant permissions in the following ways:

  • Criteri di accesso condivisi a livello di hub IoT.IoT hub-level shared access policies. I criteri di accesso condiviso possono concedere qualsiasi combinazione di autorizzazioni.Shared access policies can grant any combination of permissions. È possibile definire i criteri nel portale di Azure o a livello di codice usando le API REST del provider di risorse dell'hub IoT.You can define policies in the Azure portal, or programmatically by using the IoT Hub resource provider REST APIs. Un hub IoT appena creato ha i criteri predefiniti seguenti:A newly created IoT hub has the following default policies:

    • iothubowner: criteri con tutte le autorizzazioni.iothubowner: Policy with all permissions.
    • service: criteri con autorizzazione ServiceConnect.service: Policy with ServiceConnect permission.
    • device: criteri con autorizzazione DeviceConnect.device: Policy with DeviceConnect permission.
    • registryRead: criteri con autorizzazione RegistryRead.registryRead: Policy with RegistryRead permission.
    • registryReadWrite: criteri con autorizzazioni RegistryRead e RegistryWrite.registryReadWrite: Policy with RegistryRead and RegistryWrite permissions.
    • Credenziali di sicurezza specifiche del dispositivo.Per-device security credentials. Ogni hub IoT contiene un registro delle identità.Each IoT Hub contains an identity registry. Per ogni dispositivo presente in questo registro delle identità è possibile configurare credenziali di sicurezza che concedono autorizzazioni DeviceConnect con ambito agli endpoint di dispositivo corrispondenti.For each device in this identity registry, you can configure security credentials that grant DeviceConnect permissions scoped to the corresponding device endpoints.

Ad esempio, in una soluzione IoT tipica:For example, in a typical IoT solution:

  • Il componente di gestione dei dispositivi usa i criteri registryReadWrite .The device management component uses the registryReadWrite policy.
  • Il componente processore di eventi usa i criteri service .The event processor component uses the service policy.
  • Il componente della logica di business di runtime del dispositivo usa i criteri service .The run-time device business logic component uses the service policy.
  • I singoli dispositivi si connettono usando le credenziali archiviate nel registro delle identità dell'hub IoT.Individual devices connect using credentials stored in the IoT hub's identity registry.

Nota

Per informazioni dettagliate, vedere Autorizzazioni.See permissions for detailed information.

AuthenticationAuthentication

L'hub IoT di Azure concede l'accesso agli endpoint tramite la verifica di un token rispetto ai criteri di accesso condiviso e alle credenziali di sicurezza del registro delle identità.Azure IoT Hub grants access to endpoints by verifying a token against the shared access policies and identity registry security credentials.

Le credenziali di sicurezza, ad esempio le chiavi asimmetriche, non vengono mai trasmesse in rete.Security credentials, such as symmetric keys, are never sent over the wire.

Nota

Il provider di risorse dell'hub IoT di Azure viene protetto tramite la sottoscrizione di Azure, analogamente a tutti i provider in Azure Resource Manager.The Azure IoT Hub resource provider is secured through your Azure subscription, as are all providers in the Azure Resource Manager.

Per altre informazioni sulla creazione e sull'uso di token di sicurezza, vedere Token di sicurezza dell'hub IoT.For more information about how to construct and use security tokens, see IoT Hub security tokens.

Specifiche del protocolloProtocol specifics

Ogni protocollo supportato, ad esempio MQTT, AMQP e HTTPS, trasporta i token in modo diverso.Each supported protocol, such as MQTT, AMQP, and HTTPS, transports tokens in different ways.

Quando si usa MQTT, il pacchetto CONNECT ha deviceId come valore di ClientId, {iothubhostname}/{deviceId} nel campo Username e un token di firma di accesso condiviso nel campo Password.When using MQTT, the CONNECT packet has the deviceId as the ClientId, {iothubhostname}/{deviceId} in the Username field, and a SAS token in the Password field. Il valore di {iothubhostname} deve essere il record CName completo dell'hub IoT, ad esempio contoso.azure-devices.net.{iothubhostname} should be the full CName of the IoT hub (for example, contoso.azure-devices.net).

Quando si usa AMQP, l'hub IoT supporta SASL PLAIN e la sicurezza basata sulle attestazioni AMQP.When using AMQP, IoT Hub supports SASL PLAIN and AMQP Claims-Based-Security.

Se si usa la sicurezza basata sulle attestazioni AMQP, lo standard specifica come trasmettere questi token.If you use AMQP claims-based-security, the standard specifies how to transmit these tokens.

Per SASL PLAIN username può essere:For SASL PLAIN, the username can be:

  • {policyName}@sas.root.{iothubName} nel caso di token a livello di hub IoT.{policyName}@sas.root.{iothubName} if using IoT hub-level tokens.
  • {deviceId}@sas.{iothubname} ne caso di token con ambito relativo al dispositivo.{deviceId}@sas.{iothubname} if using device-scoped tokens.

In entrambi i casi, il campo della password contiene il token, come descritto in Token di sicurezza dell'hub IoT.In both cases, the password field contains the token, as described in IoT Hub security tokens.

Il protocollo HTTPS implementa l'autenticazione includendo un token valido nell'intestazione della richiesta Authorization .HTTPS implements authentication by including a valid token in the Authorization request header.

EsempioExample

Nome utente (per DeviceId viene fatta distinzione tra maiuscole e minuscole): iothubname.azure-devices.net/DeviceIdUsername (DeviceId is case-sensitive): iothubname.azure-devices.net/DeviceId

Password (generare il token di firma di accesso condiviso con lo strumento Device Explorer): SharedAccessSignature sr=iothubname.azure-devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501Password (Generate SAS token with the device explorer tool): SharedAccessSignature sr=iothubname.azure-devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501

Nota

Gli Azure IoT SDK generano automaticamente i token durante la connessione al servizio.The Azure IoT SDKs automatically generate tokens when connecting to the service. In alcuni casi, gli Azure IoT SDK non supportano tutti i protocolli o tutti i metodi di autenticazione.In some cases, the Azure IoT SDKs do not support all the protocols or all the authentication methods.

Considerazioni speciali su SASL PLAINSpecial considerations for SASL PLAIN

Quando si usa SASL PLAIN con AMQP, un client che si connette a un hub IoT potrà usare un singolo token per ogni connessione TCP.When using SASL PLAIN with AMQP, a client connecting to an IoT hub can use a single token for each TCP connection. Quando il token scade, la connessione TCP si disconnette dal servizio e attiva una riconnessione.When the token expires, the TCP connection disconnects from the service and triggers a reconnection. Questo comportamento non genera problemi per un'app back-end, ma è dannoso per un'app per dispositivi per i motivi seguenti:This behavior, while not problematic for a back-end app, is damaging for a device app for the following reasons:

  • I gateway si connettono in genere per conto di molti dispositivi.Gateways usually connect on behalf of many devices. Quando si usa SASL PLAIN, devono creare una connessione TCP distinta per ogni dispositivo che si connette a un hub IoT.When using SASL PLAIN, they have to create a distinct TCP connection for each device connecting to an IoT hub. Questo scenario aumenta in modo considerevole il consumo energetico e delle risorse di rete e incrementa la latenza della connessione di ogni dispositivo.This scenario considerably increases the consumption of power and networking resources, and increases the latency of each device connection.
  • L'aumento dell'uso delle risorse per la riconnessione dopo la scadenza di ogni token influisce negativamente sui dispositivi vincolati alle risorse.Resource-constrained devices are adversely affected by the increased use of resources to reconnect after each token expiration.

Definire l'ambito delle credenziali a livello di hub IoTScope IoT hub-level credentials

È possibile definire l'ambito dei criteri di sicurezza a livello di hub IoT creando token con URI di risorsa con limitazioni.You can scope IoT hub-level security policies by creating tokens with a restricted resource URI. L'endpoint per l'invio di messaggi da dispositivo a cloud da un dispositivo, ad esempio, è /devices/{deviceId}/messages/events.For example, the endpoint to send device-to-cloud messages from a device is /devices/{deviceId}/messages/events. È anche possibile usare criteri di accesso condiviso a livello di hub IoT con autorizzazioni DeviceConnect per firmare un token il cui valore resourceURI è /devices/{deviceId}.You can also use an IoT hub-level shared access policy with DeviceConnect permissions to sign a token whose resourceURI is /devices/{deviceId}. Questo approccio crea un token che può essere usato solo per l'invio di messaggi per conto del dispositivo deviceId.This approach creates a token that is only usable to send messages on behalf of device deviceId.

Questo meccanismo è simile ai criteri dell'entità di pubblicazione di Hub eventi e consente di implementare metodi di autenticazione personalizzati.This mechanism is similar to the Event Hubs publisher policy, and enables you to implement custom authentication methods.

Token di sicurezzaSecurity tokens

Hub IoT usa i token di sicurezza per autenticare i dispositivi e i servizi ed evitare l'invio in rete delle chiavi.IoT Hub uses security tokens to authenticate devices and services to avoid sending keys on the wire. Inoltre, i token di sicurezza hanno una validità limitata in termini di tempo e portata.Additionally, security tokens are limited in time validity and scope. Gli Azure IoT SDK generano automaticamente i token senza richiedere una configurazione speciale.Azure IoT SDKs automatically generate tokens without requiring any special configuration. In alcuni scenari è necessario generare e usare direttamente i token di sicurezza.Some scenarios do require you to generate and use security tokens directly. Tali scenari includono:Such scenarios include:

Hub IoT consente ai dispositivi di autenticarsi con l'hub IoT usando certificati X.509.IoT Hub also allows devices to authenticate with IoT Hub using X.509 certificates.

Formato del token di sicurezzaSecurity token structure

I token di sicurezza consentono di concedere a dispositivi e servizi l'accesso con limite temporale a funzionalità specifiche dell'hub IoT.You use security tokens to grant time-bounded access to devices and services to specific functionality in IoT Hub. Per ottenere l'autorizzazione per connettersi all'hub IoT, i dispositivi e i servizi devono inviare i token di sicurezza firmati con una chiave di accesso condiviso o una chiave simmetrica.To get authorization to connect to IoT Hub, devices and services must send security tokens signed with either a shared access or symmetric key. Tali chiavi vengono archiviate con un'identità del dispositivo nel registro delle identità.These keys are stored with a device identity in the identity registry.

Un token firmato con una chiave di accesso condiviso concede l'accesso a tutte le funzionalità associate alle autorizzazioni dei criteri di accesso condiviso.A token signed with a shared access key grants access to all the functionality associated with the shared access policy permissions. Un token firmato con una chiave simmetrica dell'identità dispositivo concede solo l'autorizzazione DeviceConnect per l'identità del dispositivo associato.A token signed with a device identity's symmetric key only grants the DeviceConnect permission for the associated device identity.

Il token di sicurezza ha il formato seguente:The security token has the following format:

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

I valori previsti sono i seguenti:Here are the expected values:

ValoreValue DescrizioneDescription
{signature}{signature} Stringa della firma HMAC-SHA256 nel formato: {URL-encoded-resourceURI} + "\n" + expiry.An HMAC-SHA256 signature string of the form: {URL-encoded-resourceURI} + "\n" + expiry. Importante: la chiave viene decodificata dalla codifica Base64 e usata come chiave per eseguire il calcolo di HMAC-SHA256.Important: The key is decoded from base64 and used as key to perform the HMAC-SHA256 computation.
{resourceURI}{resourceURI} Prefisso URI (per segmento) degli endpoint a cui è possibile accedere tramite questo token e che inizia con il nome host dell'hub IoT senza il protocollo.URI prefix (by segment) of the endpoints that can be accessed with this token, starting with host name of the IoT hub (no protocol). Ad esempio: myHub.azure-devices.net/devices/device1For example, myHub.azure-devices.net/devices/device1
{expiry}{expiry} Stringhe UTF8 per il numero di secondi trascorsi dalle 00:00:00 UTC dell'1 gennaio 1970.UTF8 strings for number of seconds since the epoch 00:00:00 UTC on 1 January 1970.
{URL-encoded-resourceURI}{URL-encoded-resourceURI} Codifica URL con lettere minuscole dell'URI della risorsa con lettere minuscoleLower case URL-encoding of the lower case resource URI
{policyName}{policyName} Nome del criterio di accesso condiviso a cui fa riferimento il token.The name of the shared access policy to which this token refers. Assente se il token fa riferimento a credenziali del registro dei dispositivi.Absent if the token refers to device-registry credentials.

Nota sul prefisso: il prefisso dell'URI viene calcolato in base al segmento e non in base al carattere.Note on prefix: The URI prefix is computed by segment and not by character. Ad esempio /a/b è un prefisso per /a/b/c ma non per /a/bc.For example /a/b is a prefix for /a/b/c but not for /a/bc.

Il frammento seguente di Node.js mostra una funzione denominata generateSasToken che calcola il token dagli input resourceUri, signingKey, policyName, expiresInMins.The following Node.js snippet shows a function called generateSasToken that computes the token from the inputs resourceUri, signingKey, policyName, expiresInMins. Nelle sezioni successive viene illustrato nel dettaglio come inizializzare gli input a seconda del caso d'uso.The next sections detail how to initialize the different inputs for the different token use cases.

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 autorization string
    var token = "SharedAccessSignature sr=" + resourceUri + "&sig="
    + base64UriEncoded + "&se=" + expires;
    if (policyName) token += "&skn="+policyName;
    return token;
};

Per fare un confronto, l'equivalente in termini di codice Python per generare un token di sicurezza è:As a comparison, the equivalent Python code to generate a security token is:

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib 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))
    }

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

    return 'SharedAccessSignature ' + urlencode(rawtoken)

La funzionalità di C# per generare un token di sicurezza è la seguente:The functionality in C# to generate a security token is:

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).ToLower() + "\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).ToLower(), WebUtility.UrlEncode(signature), expiry);

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

    return token;
}

Nota

Poiché la validità temporale del token viene verificata sui computer hub IoT, lo sfasamento dell'orologio del computer che genera il token deve essere minimo.Since the time validity of the token is validated on IoT Hub machines, the drift on the clock of the machine that generates the token must be minimal.

Usare i token di firma di accesso condiviso in un dispositivo clientUse SAS tokens in a device app

Esistono due modi per ottenere le autorizzazioni DeviceConnect con l'hub IoT con i token di sicurezza: usare una chiave del dispositivo simmetrica dal registro delle identità oppure usare una chiave di accesso condiviso.There are two ways to obtain DeviceConnect permissions with IoT Hub with security tokens: use a symmetric device key from the identity registry, or use a shared access key.

Tenere presente che, per impostazione predefinita, tutte le funzionalità accessibili dai dispositivi vengono esposte negli endpoint con il prefisso /devices/{deviceId}.Remember that all functionality accessible from devices is exposed by design on endpoints with prefix /devices/{deviceId}.

Importante

L'unico modo di cui dispone l'hub IoT per autenticare un dispositivo specifico è tramite la chiave simmetrica identità dispositivo.The only way that IoT Hub authenticates a specific device is using the device identity symmetric key. Nei casi in cui si acceda alle funzionalità del dispositivo tramite criteri di accesso condiviso, la soluzione deve considerare il componente che emette il token di sicurezza come sottocomponente attendibile.In cases when a shared access policy is used to access device functionality, the solution must consider the component issuing the security token as a trusted subcomponent.

Gli endpoint per il dispositivo sono, indipendentemente dal protocollo:The device-facing endpoints are (irrespective of the protocol):

EndpointEndpoint FunzionalitàFunctionality
{iot hub host name}/devices/{deviceId}/messages/events Invio di messaggi da dispositivo a cloud.Send device-to-cloud messages.
{iot hub host name}/devices/{deviceId}/messages/devicebound Ricezione di messaggi da cloud a dispositivo.Receive cloud-to-device messages.

Usare una chiave simmetrica nel registro identitàUse a symmetric key in the identity registry

Quando si usa una chiave simmetrica dell'identità del dispositivo per generare un token, l'elemento policyName (skn) del token viene omesso.When using a device identity's symmetric key to generate a token, the policyName (skn) element of the token is omitted.

Ad esempio, un token creato per accedere a tutte le funzionalità del dispositivo deve avere i seguenti parametri:For example, a token created to access all device functionality should have the following parameters:

  • URI della risorsa: {IoT hub name}.azure-devices.net/devices/{device id},resource URI: {IoT hub name}.azure-devices.net/devices/{device id},
  • Chiave di firma: qualsiasi chiave simmetrica per l'identità {device id} ,signing key: any symmetric key for the {device id} identity,
  • Nessun nome di criterio,no policy name,
  • Qualsiasi ora di scadenza.any expiration time.

Un esempio di uso della funzione di Node.js precedente sarebbe il seguente:An example using the preceding Node.js function would be:

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

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

Il risultato, che concede l'accesso a tutte le funzionalità per device1, sarà:The result, which grants access to all functionality for device1, would be:

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

Nota

È possibile generare un token SAS con lo strumento Esplora dispositivi di .NET o tramite l'utilità da riga di comando iothub-explorer, multipiattaforma e basata su nodi.It is possible to generate a SAS token using the .NET device explorer tool or the cross-platform, node-based iothub-explorer command-line utility.

Usare criteri di accesso condivisoUse a shared access policy

Quando si crea un token da criteri di accesso condiviso, impostare il campo skn sul nome dei criteri.When you create a token from a shared access policy, set the skn field to the name of the policy. Questi criteri devono concedere l'autorizzazione DeviceConnect.This policy must grant the DeviceConnect permission.

I due scenari principali per l'uso di criteri di accesso condiviso per accedere alla funzionalità dei dispositivi sono:The two main scenarios for using shared access policies to access device functionality are:

Poiché i criteri di accesso condiviso possono potenzialmente autorizzare la connessione a qualsiasi dispositivo, in fase di creazione dei token di sicurezza è importante usare l'URI risorsa corretto.Since the shared access policy can potentially grant access to connect as any device, it is important to use the correct resource URI when creating security tokens. Questa impostazione è particolarmente importante per i servizi token, che devono limitare l'ambito del token a un dispositivo specifico usando l'URI risorsa.This setting is especially important for token services, which have to scope the token to a specific device using the resource URI. Questo punto è meno importante per i gateway di protocollo, in quanto già filtrano il traffico per tutti i dispositivi.This point is less relevant for protocol gateways as they are already mediating traffic for all devices.

Ad esempio, un servizio token che usa il criterio di accesso condiviso già esistente denominato device creerebbe un token con i parametri seguenti:As an example, a token service using the pre-created shared access policy called device would create a token with the following parameters:

  • URI della risorsa: {IoT hub name}.azure-devices.net/devices/{device id},resource URI: {IoT hub name}.azure-devices.net/devices/{device id},
  • chiave di firma: una delle chiavi del criterio device ,signing key: one of the keys of the device policy,
  • nome criterio: device,policy name: device,
  • Qualsiasi ora di scadenza.any expiration time.

Un esempio di uso della funzione di Node.js precedente sarebbe il seguente:An example using the preceding Node.js function would be:

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

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

Il risultato, che concede l'accesso a tutte le funzionalità per device1, sarà:The result, which grants access to all functionality for device1, would be:

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

Un gateway di protocollo potrebbe usare lo stesso token per tutti i dispositivi semplicemente impostando l'URI della risorsa su myhub.azure-devices.net/devices.A protocol gateway could use the same token for all devices simply setting the resource URI to myhub.azure-devices.net/devices.

Usare token di sicurezza da componenti del servizioUse security tokens from service components

I componenti del servizio possono generare token di sicurezza solo usando criteri di accesso condiviso che concedono le autorizzazioni appropriate, come illustrato prima.Service components can only generate security tokens using shared access policies granting the appropriate permissions as explained previously.

Di seguito vengono indicate le funzioni del servizio esposte sugli endpoint:Here is the service functions exposed on the endpoints:

EndpointEndpoint FunzionalitàFunctionality
{iot hub host name}/devices Creazione, aggiornamento, recupero ed eliminazione delle identità dispositivo.Create, update, retrieve, and delete device identities.
{iot hub host name}/messages/events Ricezione di messaggi da dispositivo a cloud.Receive device-to-cloud messages.
{iot hub host name}/servicebound/feedback Ricezione di feedback per messaggi da cloud a dispositivo.Receive feedback for cloud-to-device messages.
{iot hub host name}/devicebound Invio di messaggi da cloud a dispositivo.Send cloud-to-device messages.

Ad esempio, un servizio che usa il criterio di accesso condiviso già esistente denominato registryRead creerebbe un token con i parametri seguenti:As an example, a service generating using the pre-created shared access policy called registryRead would create a token with the following parameters:

  • URI della risorsa: {IoT hub name}.azure-devices.net/devices,resource URI: {IoT hub name}.azure-devices.net/devices,
  • chiave di firma: una delle chiavi del criterio registryRead ,signing key: one of the keys of the registryRead policy,
  • nome criterio: registryRead,policy name: registryRead,
  • Qualsiasi ora di scadenza.any expiration time.
var endpoint ="myhub.azure-devices.net/devices";
var policyName = 'device';
var policyKey = '...';

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

Il risultato, che concede l'accesso in lettura a tutte le identità dispositivo, sarà:The result, which would grant access to read all device identities, would be:

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

Certificati X.509 supportatiSupported X.509 certificates

È possibile usare qualsiasi certificato X.509 per autenticare un dispositivo con hub IoT.You can use any X.509 certificate to authenticate a device with IoT Hub. I certificati inclusi sono i seguenti:Certificates include:

  • Un certificato X.509 esistente.An existing X.509 certificate. Un dispositivo potrebbe già avere un certificato X.509 associato.A device may already have an X.509 certificate associated with it. Il dispositivo può usare questo certificato per autenticarsi con hub IoT.The device can use this certificate to authenticate with IoT Hub.
  • Un certificato X-509 auto-generato e auto-firmato.A self-generated and self-signed X-509 certificate. Un produttore di dispositivi o un distributore interno può generare questi certificati e archiviare la chiave privata corrispondente (e il certificato) nel dispositivo.A device manufacturer or in-house deployer can generate these certificates and store the corresponding private key (and certificate) on the device. È possibile usare strumenti come OpenSSL e l'utilità Windows SelfSignedCertificate per questo scopo.You can use tools such as OpenSSL and Windows SelfSignedCertificate utility for this purpose.
  • Certificato X.509 firmato da un'autorità di certificazione.CA-signed X.509 certificate. Per identificare un dispositivo e autenticarlo con l'hub IoT, è possibile usare un certificato X.509 generato e firmato da un'autorità di certificazione (CA).To identify a device and authenticate it with IoT Hub, you can use an X.509 certificate generated and signed by a Certification Authority (CA). L'hub IoT verifica solo che l'identificazione personale presentata corrisponda all'identificazione personale configurata.IoT Hub only verifies that the thumbprint presented matches the configured thumbprint. IoTHub non convalida la catena di certificati.IotHub does not validate the certificate chain.

Un dispositivo può usare un certificato X.509 o un token di sicurezza per l'autenticazione, ma non per entrambi.A device may either use an X.509 certificate or a security token for authentication, but not both.

Registrare un certificato X.509 per un dispositivoRegister an X.509 certificate for a device

Il componente Azure IoT SDK per servizi per C# (versione 1.0.8+) supporta la registrazione di un dispositivo che usa un certificato X.509 per l'autenticazione.The Azure IoT Service SDK for C# (version 1.0.8+) supports registering a device that uses an X.509 certificate for authentication. Anche altre API come quelle per l'importazione e l'esportazione dei dispositivi supportano i certificati X.509.Other APIs such as import/export of devices also support X.509 certificates.

Supporto per C#C# Support

La classe RegistryManager offre un modo di registrare un dispositivo a livello di codice.The RegistryManager class provides a programmatic way to register a device. In particolare, i metodi AddDeviceAsync e UpdateDeviceAsync consentono di registrare e aggiornare un dispositivo nel registro delle identità dell'hub IoT.In particular, the AddDeviceAsync and UpdateDeviceAsync methods enable you to register and update a device in the IoT Hub identity registry. Questi due metodi accettano un'istanza Device come input.These two methods take a Device instance as input. La classe Device include una proprietà Authentication che consente di specificare le identificazioni primarie e secondarie del certificato X.509.The Device class includes an Authentication property that allows you to specify primary and secondary X.509 certificate thumbprints. L'identificazione personale rappresenta un hash SHA-1 del certificato X.509 archiviato usando la codifica DER binaria.The thumbprint represents a SHA-1 hash of the X.509 certificate (stored using binary DER encoding). Gli utenti hanno la possibilità di specificare un'identificazione personale primaria, una secondaria o entrambe.You have the option of specifying a primary thumbprint or a secondary thumbprint or both. Le identificazioni personali primarie e secondarie sono supportate per gestire scenari di rollover dei certificati.Primary and secondary thumbprints are supported to handle certificate rollover scenarios.

Nota

L'hub IoT non richiede o archivia l'intero certificato X.509 ma solo l'identificazione personale.IoT Hub does not require or store the entire X.509 certificate, only the thumbprint.

Ecco un frammento di codice C# di esempio per registrare un dispositivo usando un certificato X.509:Here is a sample C# code snippet to register a device using an X.509 certificate:

var device = new Device(deviceId)
{
  Authentication = new AuthenticationMechanism()
  {
    X509Thumbprint = new X509Thumbprint()
    {
      PrimaryThumbprint = "921BC9694ADEB8929D4F7FE4B9A3A6DE58B0790B"
    }
  }
};
RegistryManager registryManager = RegistryManager.CreateFromConnectionString(deviceGatewayConnectionString);
await registryManager.AddDeviceAsync(device);

Usare un certificato X.509 durante le operazioni di runtimeUse an X.509 certificate during run-time operations

Azure IoT SDK per dispositivi per .NET (versione 1.0.11+) supporta l'uso dei certificati X.509.The Azure IoT device SDK for .NET (version 1.0.11+) supports the use of X.509 certificates.

Supporto per C#C# Support

La classe DeviceAuthenticationWithX509Certificate supporta la creazione di istanze di DeviceClient usando un certificato X.509.The class DeviceAuthenticationWithX509Certificate supports the creation of DeviceClient instances using an X.509 certificate. Il certificato X.509 deve essere nel formato PFX, denominato anche PKCS #12, che include la chiave privata.The X.509 certificate must be in the PFX (also called PKCS #12) format that includes the private key.

Di seguito è riportato un frammento di codice di esempio:Here is a sample code snippet:

var authMethod = new DeviceAuthenticationWithX509Certificate("<device id>", x509Certificate);

var deviceClient = DeviceClient.Create("<IotHub DNS HostName>", authMethod);

Autenticazione personalizzata del dispositivoCustom device authentication

È possibile usare il registro delle identità dell'hub IoT per configurare il controllo dell'accesso e le credenziali di sicurezza per ogni dispositivo usando i token.You can use the IoT Hub identity registry to configure per-device security credentials and access control using tokens. Se una soluzione IoT ha già un registro personalizzato delle identità e/o uno schema di autenticazione, valutare la possibilità di creare un servizio token per integrare l'infrastruttura con l'hub IoT.If an IoT solution already has a custom identity registry and/or authentication scheme, consider creating a token service to integrate this infrastructure with IoT Hub. In questo modo, è possibile usare altre funzionalità IoT nella soluzione.In this way, you can use other IoT features in your solution.

Un servizio token è un servizio cloud personalizzato.A token service is a custom cloud service. Usa i criteri di accesso condiviso dell'hub IoT con autorizzazioni DeviceConnect per creare token basati sul dispositivo.It uses an IoT Hub shared access policy with DeviceConnect permissions to create device-scoped tokens. Questi token abilitano la connessione di un dispositivo all'hub IoT.These tokens enable a device to connect to your IoT hub.

Passaggi del modello di servizio token

Di seguito vengono indicati i passaggi principali del modello del servizio token:Here are the main steps of the token service pattern:

  1. Creare i criteri di accesso condiviso dell'hub IoT con autorizzazioni DeviceConnect per l'hub IoT.Create an IoT Hub shared access policy with DeviceConnect permissions for your IoT hub. È possibile creare questi criteri nel portale di Azure o a livello di programmazione.You can create this policy in the Azure portal or programmatically. Il servizio token usa questi criteri per firmare i token creati.The token service uses this policy to sign the tokens it creates.
  2. Quando un dispositivo deve accedere all'hub IoT, richiede un token firmato dal servizio token.When a device needs to access your IoT hub, it requests a signed token from your token service. Il dispositivo può eseguire l'autenticazione con il registro delle identità personalizzato/lo schema di autenticazione per determinare l'identità del dispositivo usata dal servizio token per creare il token.The device can authenticate with your custom identity registry/authentication scheme to determine the device identity that the token service uses to create the token.
  3. Il servizio token restituisce un token.The token service returns a token. Il token viene creato usando /devices/{deviceId} come resourceURI, con deviceId come dispositivo da autenticare.The token is created by using /devices/{deviceId} as resourceURI, with deviceId as the device being authenticated. Il servizio token usa i criteri di accesso condivisi per costruire il token.The token service uses the shared access policy to construct the token.
  4. Il dispositivo usa il token direttamente con l'hub IoT.The device uses the token directly with the IoT hub.

Nota

È possibile usare la classe .NET SharedAccessSignatureBuilder o la classe Java IotHubServiceSasToken per creare un token nel servizio token.You can use the .NET class SharedAccessSignatureBuilder or the Java class IotHubServiceSasToken to create a token in your token service.

Il servizio token può impostare la scadenza del token, in base alle esigenze.The token service can set the token expiration as desired. Quando il token scade, l'hub IoT interrompe la connessione del dispositivo.When the token expires, the IoT hub severs the device connection. Quindi, il dispositivo deve richiedere un nuovo token dal servizio token.Then, the device must request a new token from the token service. Un intervallo di scadenza breve aumenta il carico sia sul dispositivo che sul servizio token.A short expiry time increases the load on both the device and the token service.

Perché un dispositivo si connetta all'hub, è comunque necessario aggiungerlo al registro delle identità dell'hub IoT anche se il dispositivo usa un token e non una chiave di dispositivo per la connessione.For a device to connect to your hub, you must still add it to the IoT Hub identity registry — even though the device is using a token and not a device key to connect. È quindi possibile continuare a usare il controllo dell'accesso per ogni dispositivo abilitando o disabilitando le identità dei dispositivi nel registro delle identità.Therefore, you can continue to use per-device access control by enabling or disabling device identities in the identity registry. In questo modo si riduce il rischio che vengano usati token con intervalli di scadenza prolungati.This approach mitigates the risks of using tokens with long expiry times.

Confronto con un gateway personalizzatoComparison with a custom gateway

Il modello di servizio token è il metodo consigliato per implementare uno schema di autenticazione/registro di identità personalizzato con l'hub IoT.The token service pattern is the recommended way to implement a custom identity registry/authentication scheme with IoT Hub. Questo schema è consigliato perché l'hub IoT continua a gestire la maggior parte del traffico della soluzione.This pattern is recommended because IoT Hub continues to handle most of the solution traffic. Tuttavia, se lo schema di autenticazione personalizzato è molto legato al protocollo, può essere necessario un gateway personalizzato per elaborare tutto il traffico.However, if the custom authentication scheme is so intertwined with the protocol, you may require a custom gateway to process all the traffic. Un esempio di tale scenario prevede l'uso del protocollo TLS (Transport Layer Security) e di chiavi precondivise.An example of such a scenario is usingTransport Layer Security (TLS) and pre-shared keys (PSKs). Per altre informazioni, vedere l'articolo relativo al gateway del protocollo.For more information, see the protocol gateway article.

Argomenti di riferimento:Reference topics:

Gli argomenti di riferimento seguenti offrono altre informazioni sul controllo dell'accesso all'hub IoT.The following reference topics provide you with more information about controlling access to your IoT hub.

Autorizzazioni per l'hub IoTIoT Hub permissions

La tabella seguente elenca le autorizzazioni che è possibile usare per controllare l'accesso all'hub IoT.The following table lists the permissions you can use to control access to your IoT hub.

AutorizzazionePermission NoteNotes
RegistryReadRegistryRead Concede l'accesso di sola lettura al registro di identità.Grants read access to the identity registry. Per altre informazioni, vedere Registro delle identità.For more information, see Identity registry.
Questa autorizzazione viene usata dai servizi cloud back-end.This permission is used by back-end cloud services.
RegistryReadWriteRegistryReadWrite Concede l'accesso di lettura e scrittura al registro di identità.Grants read and write access to the identity registry. Per altre informazioni, vedere Registro delle identità.For more information, see Identity registry.
Questa autorizzazione viene usata dai servizi cloud back-end.This permission is used by back-end cloud services.
ServiceConnectServiceConnect Concede l'accesso alle comunicazioni per il servizio cloud e al monitoraggio degli endpoint.Grants access to cloud service-facing communication and monitoring endpoints.
Concede l'autorizzazione per la ricezione di messaggi da dispositivo a cloud, l'invio di messaggi da cloud a dispositivo e il recupero degli acknowledgment di recapito corrispondenti.Grants permission to receive device-to-cloud messages, send cloud-to-device messages, and retrieve the corresponding delivery acknowledgments.
Concede l'autorizzazione per il recupero degli acknowledgement di recapito per caricamenti di file.Grants permission to retrieve delivery acknowledgements for file uploads.
Concede l'autorizzazione per l'accesso a dispositivi gemelli per l'aggiornamento dei tag e delle proprietà indicate, il recupero delle proprietà segnalate e l'esecuzione di query.Grants permission to access device twins to update tags and desired properties, retrieve reported properties, and run queries.
Questa autorizzazione viene usata dai servizi cloud back-end.This permission is used by back-end cloud services.
DeviceConnectDeviceConnect Concede l'accesso agli endpoint per il dispositivo.Grants access to device-facing endpoints.
Concede l'autorizzazione per l'invio di messaggi da dispositivo a cloud e la ricezione di messaggi da cloud a dispositivo.Grants permission to send device-to-cloud messages and receive cloud-to-device messages.
Concede l'autorizzazione per il caricamento di file da un dispositivo.Grants permission to perform file upload from a device.
Concede l'autorizzazione per la ricezione di notifiche su particolari proprietà del dispositivo gemello e l'aggiornamento delle proprietà segnalate di quest'ultimo.Grants permission to receive device twin desired property notifications and update device twin reported properties.
Concede l'autorizzazione per il caricamento di file.Grants permission to perform file uploads.
Questa autorizzazione viene usata dai dispositivi.This permission is used by devices.

Materiale di riferimentoAdditional reference material

Di seguito sono indicati altri argomenti di riferimento reperibili nella Guida per gli sviluppatori dell'hub IoT:Other reference topics in the IoT Hub developer guide include:

  • Endpoint dell'hub IoT illustra i diversi endpoint esposti da ogni hub IoT per operazioni della fase di esecuzione e di gestione.IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management operations.
  • Quote e limitazioni descrive le quote e i comportamenti di limitazione applicabili al servizio hub IoT.Throttling and quotas describes the quotas and throttling behaviors that apply to the IoT Hub service.
  • Azure IoT SDK per dispositivi e servizi elenca gli SDK nei diversi linguaggi che è possibile usare quando si sviluppano app per dispositivi e servizi che interagiscono con l'hub IoT.Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
  • Linguaggio di query dell'hub IoT descrive il linguaggio di query che è possibile usare per recuperare informazioni dall'hub IoT sui dispositivi gemelli e sui processi.IoT Hub query language describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.
  • Supporto di MQTT nell'hub IoT offre altre informazioni sul supporto dell'hub IoT per il protocollo MQTT.IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

Passaggi successiviNext steps

In questa esercitazione si è appreso come controllare l'accesso all'hub IoT. Altri argomenti di interesse disponibili nella Guida per sviluppatori sono i seguenti:Now that you have learned how to control access IoT Hub, you may be interested in the following IoT Hub developer guide topics:

Per provare alcuni dei concetti descritti in questo articolo, vedere le esercitazioni sull'hub IoT seguenti:If you would like to try out some of the concepts described in this article, see the following IoT Hub tutorials: