Controlar o acesso ao DPS (Serviço de Provisionamento de Dispositivos) do Hub IoT do Azure com assinaturas de acesso compartilhado e tokens de segurança

Este artigo descreve as opções disponíveis para proteger o DPS (Serviço de Provisionamento de Dispositivos) do Hub IoT do Azure. O serviço de provisionamento usa autenticação e permissões para conceder acesso a cada ponto de extremidade. As permissões permitem que o processo de autenticação limite o acesso a uma instância de serviço com base na funcionalidade.

Este artigo discute:

• O processo de autenticação e os tokens que o serviço de provisionamento usa para verificar permissões nas APIs REST do Serviço e do Dispositivo.

• As diferentes permissões que você pode conceder a um aplicativo de back-end para acessar a API de Serviço.

Authentication

A API de Dispositivo dá suporte à autenticação de dispositivo baseada em chave e baseada em certificado X.509.

A API de Serviço dá suporte à autenticação baseada em chave para aplicativos de back-end.

Ao usar a autenticação baseada em chave, o Serviço de Provisionamento de Dispositivos usa tokens de segurança para autenticar serviços para evitar o envio de chaves na transmissão. Além disso, os tokens de segurança são limitados em tempo de validade e escopo. Os SDKs de Provisionamento de Dispositivos do Hub IoT do Azure geram tokens automaticamente sem a necessidade de nenhuma configuração especial.

Em alguns casos, talvez seja necessário usar as APIs REST do Serviço de Provisionamento de Dispositivo HTTP diretamente, sem usar os SDKs. As seções a seguir descrevem como autenticar diretamente nas APIs REST.

Autenticação da API do dispositivo

A API de Dispositivo é usada por dispositivos para atestar o Serviço de Provisionamento de Dispositivos e receber uma conexão do Hub IoT.

Um dispositivo deve se autenticar na API do Dispositivo como parte do processo de provisionamento. O método que um dispositivo usa para autenticar é definido quando você configura um grupo de registro ou registro individual. Seja qual for o método de autenticação, o dispositivo deve emitir um HTTPS PUT para a URL a seguir para se provisionar.

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

Se estiver usando a autenticação baseada em chave, um token de segurança será passado no cabeçalho da solicitação de autorização HTTP no seguinte formato:

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

Estrutura de token de segurança para autenticação baseada em chave

O token de segurança é passado no cabeçalho da solicitação de autorização HTTP no seguinte formato:

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

Os valores esperados são:

O snippet do Python a seguir mostra uma função chamada generate_sas_token que calcula o token das entradasuri, keypolicy_nameexpiry para um registro individual usando um tipo de autenticação de chave simétrica.

from base64 import b64encode, b64decode, encode 
from hashlib import sha256 
from time import time 
from urllib.parse import quote_plus, urlencode 
from hmac import HMAC 

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

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

    return 'SharedAccessSignature ' + urlencode(rawtoken) 

print(generate_sas_token("myIdScope/registrations/mydeviceregistrationid", "00mysymmetrickey", "registration"))

A saída deve ser semelhante ao exemplo a seguir:

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

O exemplo a seguir mostra como a assinatura de acesso compartilhado é usada para autenticar com a API do Dispositivo.

curl -L -i -X PUT -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -H 'Authorization: [token]' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[ID_Scope]/registrations/[registration_id]/register?api-version=2021-06-01 

Se estiver usando um grupo de registro simétrico baseado em chave, primeiro você precisará gerar uma device symmetric chave usando a chave do grupo de registro. Use a chave primária ou secundária do grupo de registro para calcular um HMAC-SHA256 da ID de registro do dispositivo. Em seguida, o resultado é convertido no formato Base64 para obter a chave de dispositivo derivada. Para exibir exemplos de código, consulte Derivar uma chave de dispositivo. Depois que a chave simétrica do dispositivo for derivada, você poderá registrar o dispositivo usando os exemplos anteriores.

Autenticação baseada em certificado

Se você configurar um registro individual ou grupo de registro para autenticação baseada em certificado X.509, o dispositivo precisará usar seu certificado X.509 emitido para atestar à API do Dispositivo. Consulte os artigos a seguir sobre como configurar o registro e gerar o certificado do dispositivo.

• Início Rápido: Provisionar um dispositivo simulado de certificado X.509

• Criar programaticamente um grupo de registro do Serviço de Provisionamento de Dispositivos para o atestado de certificado X.509

Depois que o registro é configurado e o certificado do dispositivo emitido, o exemplo a seguir demonstra como autenticar na API do Dispositivo com o certificado X.509 do dispositivo.

curl -L -i -X PUT –cert ./[device_cert].pem –key ./[device_cert_private_key].pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[ID_Scope]/registrations/[registration_id]/register?api-version=2021-06-01 

Autenticação da API de Serviço

A API de Serviço é usada para recuperar o estado de registro e remover registros de dispositivo. O serviço também é usado por aplicativos de back-end para gerenciar programaticamente grupos individuais e grupos de registro. A API de Serviço dá suporte à autenticação baseada em chave para aplicativos de back-end.

Você deve ter permissões apropriadas para acessar qualquer um dos endpoints da API do Serviço. Por exemplo, um aplicativo de back-end deve incluir um token que contenha credenciais de segurança, juntamente com cada mensagem enviada ao serviço.

O Serviço de Provisionamento de Dispositivos do Hub IoT do Azure concede acesso aos endpoints verificando o token em relação às políticas de acesso compartilhado. As credenciais de segurança, como chaves simétricas, nunca são enviadas pela rede.

Controle de acesso e permissões

Você pode conceder permissões das seguintes maneiras:

• Políticas de autorização de acesso compartilhado. As políticas de acesso compartilhado podem conceder qualquer combinação de permissões. Você pode definir políticas no portal do Azure ou programaticamente usando as APIs REST do Serviço de Provisionamento de Dispositivos. Um serviço de provisionamento recém-criado tem a seguinte política padrão:

• provisioningserviceowner: Política com todas as permissões. Consulte permissões para obter informações detalhadas.

Para obter mais informações sobre como construir e usar tokens de segurança, consulte a próxima seção.

HTTP é o único protocolo com suporte e implementa a autenticação incluindo um token válido no cabeçalho da solicitação de autorização .

Example

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

Tokens de segurança

O Serviço de Provisionamento de Dispositivos usa tokens de segurança para autenticar serviços, evitando o envio de chaves pela rede. Além disso, os tokens de segurança são limitados em tempo de validade e escopo. Os SDKs do Serviço de Provisionamento de Dispositivos do Hub IoT do Azure geram tokens automaticamente sem a necessidade de nenhuma configuração especial. Alguns cenários exigem que você gere e use tokens de segurança diretamente. Esses cenários incluem o uso direto da superfície HTTP.

Estrutura de token de segurança

Você usa tokens de segurança para conceder acesso a funcionalidades específicas no Serviço de Provisionamento de Dispositivos do Hub IoT com tempo limitado. Para obter autorização para se conectar ao serviço de provisionamento, os serviços devem enviar tokens de segurança assinados com um acesso compartilhado ou uma chave simétrica.

Um token assinado com uma chave de acesso compartilhado concede acesso a todas as funcionalidades associadas às permissões de política de acesso compartilhado.

O token de segurança tem o seguinte formato:

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

Aqui estão os valores esperados

O snippet de Node.js a seguir mostra uma função chamada generateSasToken que calcula o token das entradas resourceUri, signingKey, policyName, expiresInMins. 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', new Buffer(signingKey, 'base64'));
    hmac.update(toSign);
    var base64UriEncoded = encodeURIComponent(hmac.digest('base64'));

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

Como comparação, o código python equivalente para gerar um token de segurança é:

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

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

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

    return 'SharedAccessSignature ' + urlencode(rawtoken)

Usar tokens de segurança de componentes de serviço

Os componentes de serviço só podem gerar tokens de segurança usando políticas de acesso compartilhado que concedem as permissões apropriadas, conforme explicado anteriormente.

Veja as funções de serviço expostas nos pontos de extremidade:

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

• URI do recurso: {mydps}.azure-devices-provisioning.net,
• chave de assinatura: uma das chaves da política enrollmentread ,
• nome da política: enrollmentread,
• qualquer validade time.backn

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

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

O resultado, que concederia acesso para ler todos os registros de registro, seria:

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

SDKs e amostras

• SDKs do Microsoft Azure IoT para Java
  • Amostra
• SDK do IoT do Microsoft Azure para .NET
  • Amostra

Artigos de referência:

Os artigos de referência a seguir fornecem mais informações sobre como controlar o acesso ao serviço de provisionamento de dispositivoS IoT.

Permissões do Serviço de Provisionamento de Dispositivos

A tabela a seguir lista as permissões que você pode usar para controlar o acesso ao Serviço de Provisionamento de Dispositivos IoT.