Controlar o acesso ao Hub IoT com Assinaturas de Acesso Compartilhado

O Hub IoT usa tokens de Assinaturas de Acesso Compartilhado (SAS) para autenticar dispositivos e serviços para evitar o envio de chaves na transmissão. Você usa tokens SAS para conceder aos dispositivos e serviços acesso de tempo limitado à funcionalidade específica do Hub IoT. Para obter autorização para se conectar ao Hub IoT, os dispositivos e serviços devem enviar tokens SAS assinados com um acesso compartilhado ou uma chave simétrica. As chaves simétricas são armazenadas com uma identidade de dispositivo no registro de identidade.

Este artigo apresenta:

• As permissões diferentes que você pode conceder a um cliente para acessar o hub IoT.
• O Hub IoT dos tokens usa para verificar as permissões.
• Como analisar credenciais para limitar o acesso a recursos específicos.
• Mecanismos de autenticação de dispositivo personalizados que usam registros de identidade de dispositivo existente ou esquemas de autenticaçã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 adequadas para acessar qualquer um dos pontos de extremidade de Hub IoT. Por exemplo, um dispositivo deve incluir um token contendo as credenciais de segurança juntamente com todas as mensagens que ele envia para o Hub IoT. No entanto, as chaves de assinatura, como as chaves simétricas do dispositivo, nunca são enviadas eletronicamente.

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 no Hub IoT. Às vezes, a autenticação é abreviada para AuthN. A autorização é o processo de confirmação de permissões para um usuário ou dispositivo autenticado no Hub IoT. Ela especifica quais recursos e comandos você tem permissão para acessar e o que você pode fazer com esses recursos e comandos. Às vezes, a autorização é abreviada para AuthZ.

Este artigo descreve a autenticação e a autorização usando Assinaturas de acesso compartilhado, o que permite 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 compartilhado 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 e permissões de acesso

Use políticas de acesso compartilhado para acesso no nível do Hub IoT e use as credenciais individuais do dispositivo para 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 Provedor de Recursos do Hub IoT ou usando o comando da CLI do Azure az iot hub policy. Um hub IoT recém-criado tem as seguintes políticas padrão:

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

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

  • Acesso aos pontos de extremidade de comunicação e monitoramento voltados para o serviço de nuvem.
  • Receba mensagens do dispositivo para a nuvem, envie mensagens da nuvem para o dispositivo e recupere as confirmações de entrega correspondentes.
  • Recupere confirmações de entrega para uploads de arquivo.
  • Acesse gêmeos para atualizar marcas e propriedades desejadas, recuperar propriedades relatadas e executar consultas.

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

  • Acesso a pontos de extremidade voltados para o dispositivo.
  • Envie mensagens do dispositivo para a nuvem e receba mensagens da nuvem para o dispositivo.
  • Execute o upload do arquivo.
  • Receba as notificações de propriedade desejadas do dispositivo gêmeo e atualize as propriedades relatadas do dispositivo gêmeo.

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

  • Acesso de leitura ao registro de identidade. Para saber mais, confira Registro de identidade.

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

  • Acesso de leitura e gravação ao registro de identidade. Para saber mais, confira Registro de identidade.

Credenciais de segurança de acordo com o dispositivo

Cada Hub IoT tem um registro de identidade que armazena informações sobre os dispositivos e módulos com permissão para se conectar a ele. Antes de um dispositivo ou módulo poder se conectar, deve existir uma entrada para esse dispositivo ou módulo no registro de identidade do Hub IoT. O dispositivo ou módulo autentica 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 associada.

Usar tokens SAS nos 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 que usa a política de acesso compartilhado pré-criada chamada RegistryRead criaria um token com os seguintes parâmetros:

• URI de recurso: {IoT hub name}.azure-devices.net,
• chave de assinatura: uma das chaves da política registryRead ,
• nome da política: registryRead,
• qualquer data 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 à leitura de todas as identidades do dispositivo no registro de identidade, seria:

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

Para obter mais exemplos, confira 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 do dispositivo para a nuvem, o envio de mensagens da nuvem para o 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 de nuvem para dispositivos, poderá usar o Microsoft Entra ID. Para saber mais, confira Autenticar com o Microsoft Entra ID.

Usar tokens SAS de dispositivos

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

Todas as funcionalidades acessíveis de dispositivos são expostas por padrão em pontos de extremidade com o prefixo /devices/{deviceId}.

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

Usar uma chave simétrica no registro de identidade

Ao usar a chave simétrica da identidade de um 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 de recurso: {IoT hub name}.azure-devices.net/devices/{device id},
• chave de assinatura: qualquer chave simétrica para a identidade {device id} ,
• sem nome de política,
• qualquer data 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 para o dispositivo1, seria:

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

Para obter mais exemplos, confira 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 campo skn como o nome da política. Essa política deve conceder a permissão DeviceConnect.

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

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

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

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

• URI de recurso: {IoT hub name}.azure-devices.net/devices/{device id},
• chave de assinatura: uma das chaves da política device ,
• nome da política: device,
• qualquer data 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 para o 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, confira 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 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 existente 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 permissões DeviceConnect para criar tokens no escopo do dispositivo ou no escopo do módulo. Esses tokens permitem que um dispositivo ou módulo se conecte ao hub IoT.

Estas são as principais etapas do padrão de serviço do token:

1. Crie uma política de acesso compartilhado do Hub IoT com permissões DeviceConnect para o Hub IoT. Você pode criar essa política no portal do Azure ou de forma programática. O serviço de token usa essa política para assinar os tokens criados.

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

3. O serviço de token retorna um token. O token é criado usando /devices/{deviceId} ou /devices/{deviceId}/modules/{moduleId} como resourceURI, com deviceId como o dispositivo sendo autenticado e moduleId como o módulo sendo autenticado. 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.

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

Para que um dispositivo/módulo se conecte ao 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 as identidades de dispositivo/módulo no registro de identidade. Essa abordagem reduz os riscos de usar tokens com tempos de expiração longos.

Comparação com um gateway personalizado

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

Gerar tokens SAS

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

• O uso direto de superfícies de 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 funcionalidades associadas às permissões da política de acesso compartilhado. Um token assinado com uma chave simétrica de uma identidade de dispositivo apenas concede 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 da CLI az iot hub generate-sas-token ou a extensão do Hub IoT do Azure para Visual Studio Code.

Estrutura de token SAS

Um token SAS tem o seguinte formato:

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

Veja os valores esperados:

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

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

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)

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

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

Especificações de protocolo

Cada protocolo com suporte, como MQTT, AMQP e HTTPS, transporta os tokens de maneiras diferentes.

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

Quando usa AMQP, o Hub IoT dá suporte ao SASL PLAIN e à Segurança baseada em declarações AMQP.

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

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

• {policyName}@sas.root.{iothubName} se forem usados tokens de nível do Hub IoT.
• {deviceId}@sas.{iothubname} se forem usados tokens no escopo do dispositivo.

Em ambos os casos, o campo 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 Authorization.

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

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

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

Considerações especiais para SASL PLAIN

Ao usar o SASL PLAIN com AMQP, um cliente que está se conectando a um hub IoT pode usar um único token para cada conexão TCP. Quando o token expirar, a conexão TCP será desconectada do serviço, disparando 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:

• Gateways normalmente se conectam em nome de vários 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 de forma considerável o consumo de energia e de recursos de rede, além de aumentar a latência de cada conexão de dispositivo.

• Os dispositivos com limitações de recursos são afetados de forma adversa pelo aumento do uso de recursos para se reconectar após cada expiração do token.

Próximas etapas

Agora que você aprendeu como controlar o acesso ao Hub IoT, pode ser interessante ler os seguintes tópicos do Guia do desenvolvedor do Hub IoT:

• Usar dispositivos gêmeos para sincronizar o estado e as configurações
• Invocar um método direto em um dispositivo
• Agendar trabalhos em vários dispositivos