Controlar o acesso ao Hub IoT usando a Assinatura de Acesso Compartilhado

Esta seção descreve as opções para proteger o Hub IoT. 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.

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.

Observação

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

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.

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. É possível definir políticas no portal do Azure programaticamente, usando as APIs REST de Recursos do Hub IoT ou usando a CLI az iot hub policy. Um hub IoT recém-criado tem as seguintes políticas padrão:

Política de acesso compartilhado Permissões
iothubowner Toda Permissão
serviço Permissões ServiceConnect
dispositivo Permissões DeviceConnect
registryRead Permissões RegistryRead
registryReadWrite Permissões RegistryRead e RegistryWrite

A tabela a seguir lista as permissões que você pode usar para controlar o acesso ao seu hub IoT.

Permissão Observações
ServiceConnect Concede acesso aos pontos de extremidade de comunicação e de monitoramento voltados para o serviço de nuvem.
Concede permissão para recebimento de mensagens do dispositivo para a nuvem, envio de mensagens da nuvem para o dispositivo e obtenção das confirmações de entrega correspondentes.
Concede permissão para recuperar as confirmações de entrega dos uploads de arquivos.
Concede permissão para acessar dispositivos ou módulos gêmeos para atualizar as marcas e propriedades desejadas, recuperar propriedades relatadas e executar consultas.
Essa permissão é usada pelos serviços de nuvem de back-end.
DeviceConnect Concede acesso aos pontos de extremidade de comunicação voltados para o dispositivo.
Concede permissão de envio de mensagens do dispositivo para a nuvem e de recebimento de mensagens da nuvem para o dispositivo.
Concede permissão para executar o upload do arquivo de um dispositivo.
Concede permissão para receber notificações de propriedade do dispositivo gêmeo desejado e atualizar propriedades relatadas do dispositivo gêmeo.
Concede permissão para executar o uploads de arquivo.
Essa permissão é usada por dispositivos.
RegistryRead Concede acesso de leitura ao Registro de identidade. Para saber mais, confira Registro de identidade.
Essa permissão é usada pelos serviços de nuvem de back-end.
RegistryReadWrite Concede acesso de leitura e gravação ao Registro de identidade. Para saber mais, confira Registro de identidade.
Essa permissão é usada pelos serviços de nuvem de back-end.

Credenciais de segurança de acordo com o dispositivo

Cada Hub IoT contém um registro de identidade Para cada dispositivo nesse registro de identidade, você pode configurar credenciais de segurança que concedem permissões de DeviceConnect com escopo nos pontos de extremidade correspondentes do dispositivo.

Tokens SAS

O Hub IoT usa tokens SAS (Assinatura de Acesso Compartilhado) para autenticar dispositivos e serviços, evitando o envio de chaves durante a transmissão. Os tokens SAS têm limite de escopo e de prazo de validade. Os SDKs do IoT do Azure geram tokens automaticamente sem precisar de configuração especial. Alguns cenários exigem que você gere e use tokens SAS diretamente. Esses cenários incluem:

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.

Estrutura de token SAS

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.

Um token SAS tem o seguinte formato:

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

Veja os valores esperados:

Valor Descrição
{signature} Uma cadeia de caracteres de assinatura HMAC-SHA256 no formato: {URL-encoded-resourceURI} + "\n" + expiry. Importante: a chave é decodificada da base64 e usada como chave para executar o cálculo de HMAC-SHA256.
{resourceURI} Prefixo de URI (por segmento) dos pontos de extremidade que podem ser acessados com esse token, começando com o nome de host do Hub IoT (sem protocolo). Os tokens SAS concedidos aos serviços de back-end têm escopo de nível de hub IoT, por exemplo, myHub.azure-devices.net. Os tokens SAS concedidos aos dispositivos devem ter o escopo de um dispositivo individual, por exemplo, myHub.azure-devices.net/devices/device1.
{expiry} As cadeias de caracteres UTF8 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 em letras minúsculas do URI de recurso em letras minúsculas
{policyName} O nome da política de acesso compartilhado a qual se refere esse token. Ausente se o token se referir às credenciais de registro do dispositivo.

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.

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 seções a seguir detalharão como inicializar as entradas diferentes para casos de uso com token diferentes.

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

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, contoso.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 de senha contém o token, conforme descrito em Tokens SAS do Hub IoT.

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 (é possível gerar um token SAS com o comando de extensão da CLI az iot hub generate-sas-token ou o Azure IoT Tools para Visual Studio Code):

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

Observação

Os SDKs do IoT do Azure geram tokens automaticamente durante a conexão com o serviço. Em alguns casos, os SDKs do IoT do Azure 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 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.

Usar tokens SAS nos serviços

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

Por exemplo, um serviço que usa a política de acesso compartilhado criada anteriormente 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
var endpoint = "myhub.azure-devices.net";
var policyName = 'registryRead';
var policyKey = '...';

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

O resultado, que concederia acesso de leitura em todas as identidades de dispositivo, seria:

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

Para serviços, os tokens SAS só concedem permissões no nível de 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 serviços, por exemplo, limitando um serviço a enviar apenas mensagens da nuvem para o dispositivo, você pode usar o Azure Active Directory. Para saber mais, confira Controlar o acesso ao Hub IoT com o Azure AD.

Autenticando um dispositivo no Hub IoT

Certificados X.509 com suporte

Você pode usar qualquer certificado X. 509 para autenticar um dispositivo com o IoT Hub, carregando uma impressão digital do certificado ou uma autoridade de certificação (CA) do Hub IoT do Azure. Para saber mais, consulte Autenticação de dispositivo usando certificados de AC X.509. Para obter informações sobre como carregar e verificar uma autoridade de certificação com o hub IoT, consulte Configurar a segurança X.509 no hub IoT do Azure.

Como aplicar a autenticação X.509

Para maior segurança, um hub IoT pode ser configurado para não permitir a autenticação de SAS para dispositivos e módulos, deixando o X.509 como a única opção de autenticação aceita. Atualmente, esse recurso não está disponível no portal do Azure. Para configurar, defina disableDeviceSAS e disableModuleSAS como true nas propriedades de recurso do Hub IoT:

az resource update -n <iothubName> -g <resourceGroupName> --resource-type Microsoft.Devices/IotHubs --set properties.disableDeviceSAS=true properties.disableModuleSAS=true

Usar tokens SAS como um dispositivo

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.

Lembre-se que toda funcionalidade acessível por meio de dispositivos fica exposta 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):

Ponto de extremidade Funcionalidade
{iot hub host name}/devices/{deviceId}/messages/events Enviar mensagens do dispositivo para a nuvem.
{iot hub host name}/devices/{deviceId}/messages/devicebound Receber mensagens da nuvem para o dispositivo.

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

Um exemplo usando a função Node.js anterior seria:

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

Observação

É possível gerar um token SAS com o comando de extensão da CLI az iot hub generate-sas-token ou o Azure IoT Tools para Visual Studio Code.

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:

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 criada anteriormente 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

Um exemplo usando a função Node.js anterior seria:

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 poderia usar o mesmo token para todos os dispositivos, simplesmente definindo o URI do recurso para myhub.azure-devices.net/devices.

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 e controle de acesso por dispositivo/módulo 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 conectem ao seu Hub IoT.

Etapas do padrão do serviço de token

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/módulo precisar acessar o Hub IoT, ele solicitará um token assinado ao 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 que está sendo autenticado ou moduleId como o módulo que está 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.

Observação

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

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 conecte-se ao hub, você ainda deverá adicioná-lo ao registro de identidade do Hub IoT — mesmo que esteja usando um token e não uma chave para 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 de tal cenário é usar TLS (Transport Layer Security) e as PSKs (chaves pré-compartilhadas). Para obter mais informações, confira Como um dispositivo IoT Edge pode ser usado como um gateway.

Material de referência adicional

Outros tópicos de referência no Guia do desenvolvedor do Hub IoT incluem:

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:

Se você quiser experimentar alguns dos conceitos descritos neste artigo, consulte os seguintes tutoriais de Hub IoT: