Controle o acesso ao Hub IoT com assinaturas de acesso compartilhado

O Hub IoT usa tokens de assinatura de acesso compartilhado (SAS) para autenticar dispositivos e serviços para evitar o envio de chaves por fio. Você usa tokens SAS para conceder acesso limitado no tempo a dispositivos e serviços para funcionalidades específicas no Hub IoT. Para obter autorização para se conectar ao Hub IoT, os dispositivos e serviços devem enviar tokens SAS assinados com acesso compartilhado ou chave simétrica. As chaves simétricas são armazenadas com uma identidade de dispositivo no registro de identidade.

Este artigo apresenta:

• As diferentes permissões que você pode conceder a um cliente para acessar seu hub IoT.
• Os tokens que o Hub IoT usa para verificar permissões.
• Como definir o escopo de credenciais para limitar o acesso a recursos específicos.
• Mecanismos de autenticação de dispositivo personalizados que usam registros de identidade de dispositivo ou esquemas de autenticação existentes.

Nota

Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, gêmeos de dispositivo e gerenciamento de dispositivos, estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.

O Hub IoT usa permissões para conceder acesso a cada ponto de extremidade do hub IoT. As permissões limitam o acesso a um hub IoT com base na funcionalidade. Você deve ter permissões apropriadas para acessar qualquer um dos pontos de extremidade do Hub IoT. Por exemplo, um dispositivo deve incluir um token contendo credenciais de segurança junto com todas as mensagens que envia ao Hub IoT. No entanto, as chaves de assinatura, como as chaves simétricas do dispositivo, nunca são enviadas através do fio.

Autenticação e autorização

A autenticação é o processo de provar que você é quem diz ser. A autenticação verifica a identidade de um usuário ou dispositivo para o Hub IoT. Às vezes é encurtado para AuthN. Autorização é o processo de confirmação de permissões para um usuário ou dispositivo autenticado no Hub IoT. Ele especifica quais recursos e comandos você tem permissão para acessar e o que você pode fazer com esses recursos e comandos. A autorização às vezes é encurtada para AuthZ.

Este artigo descreve a autenticação e a autorização usando assinaturas de acesso compartilhado, que permitem agrupar permissões e concedê-las a aplicativos usando chaves de acesso e tokens de segurança assinados. Você também pode usar chaves simétricas ou chaves de acesso compartilhadas para autenticar um dispositivo com o Hub IoT. Os tokens SAS fornecem autenticação para cada chamada feita pelo dispositivo ao Hub IoT, associando a chave simétrica a cada chamada.

Controle de acesso e permissões

Use políticas de acesso compartilhado para acesso no nível do hub IoT e use as credenciais individuais do dispositivo para definir o escopo de acesso somente a esse dispositivo.

Políticas de acesso compartilhado no nível do hub IoT

As políticas de acesso compartilhado podem conceder qualquer combinação de permissões. Você pode definir políticas no portal do Azure, programaticamente, usando as APIs REST de Recursos do Hub IoT ou usando o comando de política az iot hub da CLI do Azure. Um hub IoT recém-criado tem as seguintes políticas padrão:

Política de Acesso Partilhado	Permissões
iothubowner	Todas as permissões
service	Permissões ServiceConnect
device	Permissões do DeviceConnect
LerRegisto	RegistryRead permissões
LerEscreverRegisto	Permissões RegistryRead e RegistryWrite

Você pode usar as seguintes permissões para controlar o acesso ao seu hub IoT:

• A permissão ServiceConnect é usada por serviços de nuvem back-end e concede o seguinte acesso:

  • Acesso a terminais de comunicação e monitoramento voltados para serviços de nuvem.
  • Receba mensagens de dispositivo para nuvem, envie mensagens de nuvem para dispositivo e recupere as confirmações de entrega correspondentes.
  • Recupere confirmações de entrega para uploads de arquivos.
  • Acesse gêmeos para atualizar tags e propriedades desejadas, recuperar propriedades relatadas e executar consultas.

• A permissão DeviceConnect é usada por dispositivos e concede o seguinte acesso:

  • Acesso a terminais voltados para o dispositivo.
  • Envie mensagens do dispositivo para a nuvem e receba mensagens da nuvem para o dispositivo.
  • Execute o upload de arquivos.
  • Receba notificações de propriedades desejadas de gêmeos de dispositivos e atualize as propriedades de gêmeos de dispositivos.

• A permissão RegistryRead é usada por serviços de nuvem back-end e concede o seguinte acesso:

  • Acesso de leitura ao registro de identidade. Para obter mais informações, consulte Registro de identidade.

• A permissão RegistryReadWrite é usada por serviços de nuvem back-end e concede o seguinte acesso:

  • Acesso de leitura e gravação ao registro de identidade. Para obter mais informações, consulte Registro de identidade.

Credenciais de segurança por dispositivo

Cada hub IoT tem um registro de identidade que armazena informações sobre os dispositivos e módulos permitidos para se conectar a ele. Antes que um dispositivo ou módulo possa se conectar, deve haver uma entrada para esse dispositivo ou módulo no registro de identidade do hub IoT. Um dispositivo ou módulo é autenticado com o hub IoT com base em credenciais armazenadas no registro de identidade.

Quando você registra um dispositivo para usar a autenticação de token SAS, esse dispositivo obtém duas chaves simétricas. As chaves simétricas concedem a permissão DeviceConnect para a identidade do dispositivo associado.

Usar tokens SAS de serviços

Os serviços podem gerar tokens SAS usando uma política de acesso compartilhado que define as permissões apropriadas, conforme explicado anteriormente na seção Controle de acesso e permissões .

Por exemplo, um serviço usando a política de acesso compartilhado pré-criada chamada registryRead criaria um token com os seguintes parâmetros:

• URI do recurso: {IoT hub name}.azure-devices.net,
• chave de assinatura: uma das chaves da registryRead política,
• Nome da política: registryRead,
• qualquer tempo de validade.

Por exemplo, o código a seguir cria um token SAS no Node.js:

var endpoint = "myhub.azure-devices.net";
var policyName = 'registryRead';
var policyKey = '...';

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

O resultado, que concede acesso para ler todas as identidades de dispositivo no registro de identidade, seria:

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

Para obter mais exemplos, consulte Gerar tokens SAS.

Para serviços, os tokens SAS só concedem permissões no nível do Hub IoT. Ou seja, um serviço autenticado com um token baseado na política de serviço poderá executar todas as operações concedidas pela permissão ServiceConnect . Essas operações incluem o recebimento de mensagens de dispositivo para nuvem, o envio de mensagens de nuvem para dispositivo e assim por diante. Se você quiser conceder acesso mais granular aos seus serviços, por exemplo, limitando um serviço a enviar apenas mensagens da nuvem para o dispositivo, você pode usar o Microsoft Entra ID. Para saber mais, consulte Autenticar com o Microsoft Entra ID.

Usar tokens SAS de dispositivos

Há duas maneiras de obter permissões do DeviceConnect com o Hub IoT com tokens SAS: usar uma chave de dispositivo simétrica do registro de identidade ou usar uma chave de acesso compartilhada.

Todas as funcionalidades acessíveis a partir de dispositivos são expostas por design em pontos finais com o prefixo /devices/{deviceId}.

Os pontos finais voltados para o dispositivo são (independentemente do protocolo):

Ponto final	Caraterística
{iot hub name}/devices/{deviceId}/messages/events	Envie mensagens do dispositivo para a nuvem.
{iot hub name}/devices/{deviceId}/messages/devicebound	Receba mensagens da nuvem para o dispositivo.

Usar uma chave simétrica no registro de identidade

Ao usar a chave simétrica de uma identidade de dispositivo para gerar um token, o elemento policyName (skn) do token é omitido.

Por exemplo, um token criado para acessar todas as funcionalidades do dispositivo deve ter os seguintes parâmetros:

• URI do recurso: {IoT hub name}.azure-devices.net/devices/{device id},
• chave de assinatura: qualquer chave simétrica para a {device id} identidade,
• sem nome da política,
• qualquer tempo de validade.

Por exemplo, o código a seguir cria um token SAS no Node.js:

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

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

O resultado, que concede acesso a todas as funcionalidades do dispositivo1, seria:

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

Para obter mais exemplos, consulte Gerar tokens SAS.

Usar uma política de acesso compartilhado para acessar em nome de um dispositivo

Ao criar um token a partir de uma política de acesso compartilhado, defina o skn campo como o nome da política. Esta política deve conceder a permissão DeviceConnect .

Os dois cenários principais para usar políticas de acesso compartilhado para acessar a funcionalidade do dispositivo são:

• gateways de protocolo na nuvem,
• serviços de token usados para implementar esquemas de autenticação personalizados.

Como a política de acesso compartilhado pode potencialmente conceder acesso para se conectar como qualquer dispositivo, é importante usar o URI de recurso correto ao criar tokens SAS. Essa configuração é especialmente importante para serviços de token, que precisam definir o escopo do token para um dispositivo específico usando o URI do recurso. Este ponto é menos relevante para gateways de protocolo, pois eles já estão mediando o tráfego para todos os dispositivos.

Como exemplo, um serviço de token usando a política de acesso compartilhado precriada chamada dispositivo criaria um token com os seguintes parâmetros:

• URI do recurso: {IoT hub name}.azure-devices.net/devices/{device id},
• chave de assinatura: uma das chaves da device política,
• Nome da política: device,
• qualquer tempo de validade.

Por exemplo, o código a seguir cria um token SAS no Node.js:

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

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

O resultado, que concede acesso a todas as funcionalidades do dispositivo1, seria:

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

Um gateway de protocolo pode usar o mesmo token para todos os dispositivos definindo o URI do recurso como myhub.azure-devices.net/devices.

Para obter mais exemplos, consulte Gerar tokens SAS.

Criar um serviço de token para integrar dispositivos existentes

Você pode usar o registro de identidade do Hub IoT para configurar credenciais de segurança por dispositivo ou por módulo e controle de acesso usando tokens. Se uma solução de IoT já tiver um registro de identidade personalizado e/ou esquema de autenticação, considere a criação de um serviço de token para integrar essa infraestrutura ao Hub IoT. Dessa forma, você pode usar outros recursos de IoT em sua solução.

Um serviço de token é um serviço de nuvem personalizado. Ele usa uma política de acesso compartilhado do Hub IoT com a permissão DeviceConnect para criar tokens com escopo de dispositivo ou módulo. Esses tokens permitem que um dispositivo ou módulo se conecte ao seu hub IoT.

Aqui estão as principais etapas do padrão de serviço de token:

1. Crie uma política de acesso compartilhado do Hub IoT com a permissão DeviceConnect para seu hub IoT. Você pode criar essa política no portal do Azure ou programaticamente. O serviço de token usa essa política para assinar os tokens que cria.

2. Quando um dispositivo ou módulo precisa acessar seu hub IoT, ele solicita um token assinado do seu serviço de token. O dispositivo pode autenticar-se com o seu registo de identidade/esquema de autenticação personalizado para determinar a identidade do dispositivo/módulo que o serviço de token utiliza para criar o token.

3. O serviço de token retorna um token. O token é criado usando ou como , com deviceId como o dispositivo sendo autenticado e moduleId como o módulo sendo autenticado.resourceURI/devices/{deviceId}/modules/{moduleId} /devices/{deviceId} O serviço de token usa a política de acesso compartilhado para construir o token.

4. O dispositivo/módulo usa o token diretamente com o hub IoT.

Nota

Você pode usar a classe .NET SharedAccessSignatureBuilder ou a classe Java IotHubServiceSasToken para criar um token em seu serviço de token.

O serviço de token pode definir a expiração do token conforme desejado. Quando o token expira, o hub IoT corta a conexão dispositivo/módulo. Em seguida, o dispositivo/módulo deve solicitar um novo token do serviço de token. Um curto tempo de expiração aumenta a carga no dispositivo/módulo e no serviço de token.

Para que um dispositivo/módulo se conecte ao seu hub, você ainda deve adicioná-lo ao registro de identidade do Hub IoT, mesmo que ele esteja usando um token e não uma chave para se conectar. Portanto, você pode continuar a usar o controle de acesso por dispositivo/por módulo habilitando ou desabilitando identidades de dispositivo/módulo no registro de identidade. Essa abordagem reduz os riscos de usar tokens com longos tempos de expiração.

Comparação com um gateway personalizado

O padrão de serviço de token é a maneira recomendada de implementar um esquema de registro/autenticação de identidade personalizado com o Hub IoT. Esse padrão é recomendado porque o Hub IoT continua a lidar com a maior parte do tráfego da solução. No entanto, se o esquema de autenticação personalizada estiver tão interligado com o protocolo, você pode precisar de um gateway personalizado para processar todo o tráfego. Um exemplo desse cenário é o uso de Transport Layer Security (TLS) e chaves pré-compartilhadas (PSKs). Para obter mais informações, consulte Como um dispositivo IoT Edge pode ser usado como um gateway.

Gerar tokens SAS

Os SDKs do Azure IoT geram tokens automaticamente, mas alguns cenários exigem que você gere e use tokens SAS diretamente, incluindo:

• O uso direto das superfícies MQTT, AMQP ou HTTPS.

• A implementação do padrão de serviço de token, conforme explicado na seção Criar um serviço de token.

Um token assinado com uma chave de acesso compartilhada concede acesso a todas as funcionalidades associadas às permissões da política de acesso compartilhado. Um token assinado com a chave simétrica de uma identidade de dispositivo concede apenas a permissão DeviceConnect para a identidade do dispositivo associado.

Esta seção fornece exemplos de geração de tokens SAS em diferentes linguagens de código. Você também pode gerar tokens SAS com o comando de extensão CLI az iot hub generate-sas-token ou a extensão do Hub IoT do Azure para Visual Studio Code.

Estrutura do token SAS

Um token SAS tem o seguinte formato:

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

Aqui estão os valores esperados:

valor	Description
{assinatura}	Uma cadeia de caracteres de assinatura HMAC-SHA256 do formulário: {URL-encoded-resourceURI} + "\n" + expiry. Importante: A chave é decodificada da base64 e usada como chave para executar o cálculo HMAC-SHA256.
{resourceURI}	Prefixo URI (por segmento) dos pontos de extremidade que podem ser acessados com esse token, começando com o nome do host do hub IoT (sem protocolo). Os tokens SAS concedidos a serviços de back-end têm como escopo o nível do hub IoT; por exemplo, myHub.azure-devices.net. Os tokens SAS concedidos a dispositivos devem ter escopo para um dispositivo individual; por exemplo, myHub.azure-devices.net/devices/device1.
{prazo de validade}	UTF8 strings para o número de segundos desde a época 00:00:00 UTC em 1 de janeiro de 1970.
{URL-encoded-resourceURI}	Codificação de URL minúscula do URI de recurso minúsculo
{nome_da_política}	O nome da política de acesso compartilhado à qual esse token se refere. Ausente se o token se referir a credenciais de registro de dispositivo.

O prefixo URI é calculado por segmento e não por caractere. Por exemplo, é um prefixo para/a/b/c, /a/b mas não para /a/bc.

Node.js

O código a seguir gera um token SAS usando o URI do recurso, a chave de assinatura, o nome da política e o período de expiração. As próximas seções detalham como inicializar as diferentes entradas para os diferentes casos de uso de token.

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', Buffer.from(signingKey, 'base64'));
    hmac.update(toSign);
    var base64UriEncoded = encodeURIComponent(hmac.digest('base64'));

    // Construct authorization string
    var token = "SharedAccessSignature sr=" + resourceUri + "&sig="
    + base64UriEncoded + "&se=" + expires;
    if (policyName) token += "&skn="+policyName;
    return token;
};

Python

O código a seguir gera um token SAS usando o URI do recurso, a chave de assinatura, o nome da política e o período de expiração. As próximas seções detalham como inicializar as diferentes entradas para os diferentes casos de uso de token.

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib import parse
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600):
    ttl = time() + expiry
    sign_key = "%s\n%d" % ((parse.quote_plus(uri)), int(ttl))
    print(sign_key)
    signature = b64encode(HMAC(b64decode(key), sign_key.encode('utf-8'), sha256).digest())

    rawtoken = {
        'sr' :  uri,
        'sig': signature,
        'se' : str(int(ttl))
    }

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

    return 'SharedAccessSignature ' + parse.urlencode(rawtoken)

C#

O código a seguir gera um token SAS usando o URI do recurso, a chave de assinatura, o nome da política e o período de expiração. As próximas seções detalham como inicializar as diferentes entradas para os diferentes casos de uso de token.

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

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

    return token;
}

Java

O código a seguir gera um token SAS usando o URI do recurso e a chave de assinatura. O período de expiração é definido como uma hora a partir da hora atual. As próximas seções detalham como inicializar as diferentes entradas para os diferentes casos de uso de token.

public static String generateSasToken(String resourceUri, String key) throws Exception {
    // Token will expire in one hour
    var expiry = Instant.now().getEpochSecond() + 3600;

    String stringToSign = URLEncoder.encode(resourceUri, StandardCharsets.UTF_8) + "\n" + expiry;
    byte[] decodedKey = Base64.getDecoder().decode(key);

    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(decodedKey, "HmacSHA256");
    sha256HMAC.init(secretKey);
    Base64.Encoder encoder = Base64.getEncoder();

    String signature = new String(encoder.encode(
        sha256HMAC.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8))), StandardCharsets.UTF_8);

    String token = "SharedAccessSignature sr=" + URLEncoder.encode(resourceUri, StandardCharsets.UTF_8)
            + "&sig=" + URLEncoder.encode(signature, StandardCharsets.UTF_8.name()) + "&se=" + expiry;
            
    return token;
}

Especificidades do protocolo

Cada protocolo suportado, como MQTT, AMQP e HTTPS, transporta tokens de maneiras diferentes.

Ao usar MQTT, o pacote CONNECT tem o deviceId como ClientId, {iothubhostname}/{deviceId} no campo Username, e um token SAS no campo Password. {iothubhostname} deve ser o CName completo do hub IoT (por exemplo, myhub.azure-devices.net).

Ao usar o AMQP, o Hub IoT suporta SASL PLAIN e AMQP Claims-Based-Security.

Se você usar a segurança baseada em declarações AMQP, o padrão especifica como transmitir esses tokens.

Para SASL PLAIN, o nome de usuário pode ser:

• {policyName}@sas.root.{iothubName} se estiver usando tokens no nível do hub IoT.
• {deviceId}@sas.{iothubname} se estiver usando tokens com escopo de dispositivo.

Em ambos os casos, o campo de senha contém o token, conforme descrito na estrutura do token SAS.

O HTTPS implementa a autenticação incluindo um token válido no cabeçalho da solicitação de autorização .

Por exemplo, Nome de usuário (DeviceId diferencia maiúsculas de minúsculas): iothubname.azure-devices.net/DeviceId

Senha (Você pode gerar um token SAS com o comando de extensão CLI az iot hub generate-sas-token ou a extensão do Hub IoT do Azure para Visual Studio Code):

SharedAccessSignature sr=iothubname.azure-devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501

Nota

Os SDKs do Azure IoT geram tokens automaticamente ao se conectar ao serviço. Em alguns casos, os SDKs do Azure IoT não dão suporte a todos os protocolos ou a todos os métodos de autenticação.

Considerações especiais para SASL PLAIN

Ao usar SASL PLAIN com AMQP, um cliente que se conecta a um hub IoT pode usar um único token para cada conexão TCP. Quando o token expira, a conexão TCP se desconecta do serviço e dispara uma reconexão. Esse comportamento, embora não seja problemático para um aplicativo back-end, é prejudicial para um aplicativo de dispositivo pelos seguintes motivos:

• Os gateways geralmente se conectam em nome de muitos dispositivos. Ao usar SASL PLAIN, eles precisam criar uma conexão TCP distinta para cada dispositivo que se conecta a um hub IoT. Esse cenário aumenta consideravelmente o consumo de energia e recursos de rede e aumenta a latência de cada conexão de dispositivo.

• Os dispositivos com recursos restritos são afetados negativamente pelo aumento do uso de recursos para se reconectar após cada expiração de token.

Próximos passos

Agora que você aprendeu como controlar o acesso ao Hub IoT, pode estar interessado nos seguintes tópicos do guia do desenvolvedor do Hub IoT:

• Use gêmeos de dispositivo para sincronizar o estado e as configurações
• Invocar um método direto em um dispositivo
• Programar tarefas em vários dispositivos