Autenticar o acesso aos recursos dos Centros de Eventos usando assinaturas de acesso compartilhado (SAS)

Ao usar uma assinatura de acesso compartilhada (SAS), você pode controlar o tipo de acesso que concede aos clientes. Você pode definir os seguintes controles em um SAS:

• O intervalo no qual a SAS é válida, que inclui a hora de início e a hora de expiração.
• As permissões concedidas pelas SAS. Por exemplo, um SAS para um namespace de Hub de Eventos pode conceder permissão para ouvir eventos, mas não permissão para enviar eventos.

A autenticação SAS oferece os seguintes benefícios:

• Somente clientes que apresentam credenciais válidas podem enviar dados para um hub de eventos.
• Um cliente não pode representar outro cliente.
• Você pode bloquear um cliente malicioso de enviar dados para um hub de eventos.

Este artigo aborda a autenticação do acesso aos recursos dos Hubs de Eventos usando SAS. Para saber como autorizar acesso a recursos dos Centros de Eventos usando SAS, veja Autorizar acesso aos recursos dos Centros de Eventos usando assinaturas de acesso compartilhadas.

Configurar autenticação SAS

Você pode configurar a regra de SAS em um namespace dos Hubs de Eventos ou em uma entidade (o hub de eventos ou um tópico no Kafka). Configurar uma regra SAS em um grupo de consumidores não é suportado, mas você pode usar regras configuradas em um namespace ou entidade para garantir o acesso a um grupo de consumidores. A imagem a seguir mostra como as regras de autorização se aplicam em entidades de exemplo.

Neste exemplo, o namespace dos Hubs de Eventos de exemplo (ExampleNamespace) tem duas entidades: eh1 e topic1 no Kafka. As regras de autorização são definidas no nível da entidade e no nível do namespace.

As regras de autorização manageRuleNS, sendRuleNS e listenRuleNS se aplicam tanto ao topic1 quanto ao eh1. As regras de autorização listenRule-eh e sendRule-eh se aplicam somente a eh1, enquanto a regra de autorização sendRuleT se aplica somente ao topic1.

Ao usar a regra de autorização sendRuleNS, os aplicativos cliente podem enviar tanto para eh1 quanto topic1. Quando a regra de autorização sendRuleT é usada, ela impõe o acesso granular somente para topic1 e, portanto, os aplicativos cliente que usam essa regra para acesso não podem então enviar para eh1, mas apenas para topic1.

Gerar um token de Assinatura de Acesso Compartilhado

Qualquer cliente que tenha acesso ao nome de uma regra de autorização e uma de suas chaves de assinatura pode gerar um token SAS. Gerar o token criando uma string no seguinte formato:

• se – instante da expiração do token. Número inteiro que reflete segundos desde a época 00:00:00 UTC em 1º de janeiro de 1970 (época UNIX) quando o token expira.
• skn – nome da regra de autorização, que é o nome da chave SAS.
• sr – URI do recurso sendo acessado.
• sig – assinatura.

A cadeia de caracteres de assinatura é o hash HMAC-SHA256 calculado no SHA256 do URI do recurso (escopo conforme descrito na seção anterior) e a representação de cadeia de caracteres do instante de expiração do token, separados por uma LF (alimentação de linha). Digite o hash com uma das chaves de assinatura da regra de autorização. O cálculo de hash retorna um valor de hash de 256 bits/32 bytes.

HMAC-SHA256(signingKey, 'https://<yournamespace>.servicebus.windows.net/' + '\n' + 1438205742)

O token contém os valores não hashados para que o destinatário possa recalcular o hash com os mesmos parâmetros e verificar se o emissor possui uma chave de assinatura válida.

O URI do recurso é o URI completo do recurso do Barramento de Serviço ao qual o acesso é solicitado. Por exemplo, http://<namespace>.servicebus.windows.net/<entityPath> ou sb://<namespace>.servicebus.windows.net/<entityPath>, como http://contoso.servicebus.windows.net/eh1.

Codifique o URI usando codificação percentual.

Configure a regra de SAS usada para assinatura na entidade especificada por esse URI ou por um de seus pais hierárquicos. Por exemplo, http://contoso.servicebus.windows.net/eh1 ou http://contoso.servicebus.windows.net no exemplo anterior.

Um token SAS é válido para todos os recursos prefixados com o <resourceURI> usado na cadeia de caracteres de assinatura.

Gerar uma assinatura (token) a partir de uma apólice

A seção a seguir mostra como gerar um token SAS usando políticas de assinatura de acesso compartilhado.

Node.js

function createSharedAccessToken(uri, saName, saKey) { 
  if (!uri || !saName || !saKey) { 
          throw "Missing required parameter"; 
      } 
  var encoded = encodeURIComponent(uri); 
  var now = new Date(); 
  var week = 60*60*24*7;
  var ttl = Math.round(now.getTime() / 1000) + week;
  var signature = encoded + '\n' + ttl; 
  var hash = crypto.createHmac('sha256', saKey).update(signature, 'utf8').digest('base64'); 
  return 'SharedAccessSignature sr=' + encoded + '&sig=' +  
      encodeURIComponent(hash) + '&se=' + ttl + '&skn=' + saName; 
}

Para usar um nome de política e um valor de chave a fim de se conectar a um hub de eventos, use o construtor EventHubProducerClient que aceita o parâmetro AzureNamedKeyCredential.

const producer = new EventHubProducerClient("NAMESPACE NAME.servicebus.windows.net", eventHubName, new AzureNamedKeyCredential("POLICYNAME", "KEYVALUE"));

Adicionar uma referência a AzureNamedKeyCredential.

const { AzureNamedKeyCredential } = require("@azure/core-auth");

Para usar um token SAS que você gera usando o código, use o EventHubProducerClient construtor que recebe o AzureSASCredential parâmetro.

var token = createSharedAccessToken("https://NAMESPACENAME.servicebus.windows.net", "POLICYNAME", "KEYVALUE");
const producer = new EventHubProducerClient("NAMESPACENAME.servicebus.windows.net", eventHubName, new AzureSASCredential(token));

Adicionar uma referência a AzureSASCredential.

const { AzureSASCredential } = require("@azure/core-auth");

Java

private static String GetSASToken(String resourceUri, String keyName, String key)
  {
      long epoch = System.currentTimeMillis()/1000L;
      int week = 60*60*24*7;
      String expiry = Long.toString(epoch + week);

      String sasToken = null;
      try {
          String stringToSign = URLEncoder.encode(resourceUri, "UTF-8") + "\n" + expiry;
          String signature = getHMAC256(key, stringToSign);
          sasToken = "SharedAccessSignature sr=" + URLEncoder.encode(resourceUri, "UTF-8") +"&sig=" +
                  URLEncoder.encode(signature, "UTF-8") + "&se=" + expiry + "&skn=" + keyName;
      } catch (UnsupportedEncodingException e) {

          e.printStackTrace();
      }

      return sasToken;
  }


public static String getHMAC256(String key, String input) {
    Mac sha256_HMAC = null;
    String hash = null;
    try {
        sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        Encoder encoder = Base64.getEncoder();

        hash = new String(encoder.encode(sha256_HMAC.doFinal(input.getBytes("UTF-8"))));

    } catch (InvalidKeyException e) {
        e.printStackTrace();
    } catch (NoSuchAlgorithmException e) {
        e.printStackTrace();
   } catch (IllegalStateException e) {
        e.printStackTrace();
    } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
    }

    return hash;
}

PHP

function generateSasToken($uri, $sasKeyName, $sasKeyValue) 
{ 
    $targetUri = strtolower(rawurlencode(strtolower($uri))); 
    $expires = time(); 	
    $expiresInMins = 60; 
    $week = 60*60*24*7;
    $expires = $expires + $week; 
    $toSign = $targetUri . "\n" . $expires; 
    $signature = rawurlencode(base64_encode(hash_hmac('sha256', 			
     $toSign, $sasKeyValue, TRUE))); 
    
    $token = "SharedAccessSignature sr=" . $targetUri . "&sig=" . $signature . "&se=" . $expires . 		"&skn=" . $sasKeyName; 
    return $token; 
}

C#

private static string createToken(string resourceUri, string keyName, string key)
{
    TimeSpan sinceEpoch = DateTime.UtcNow - new DateTime(1970, 1, 1);
    var week = 60 * 60 * 24 * 7;
    var expiry = Convert.ToString((int)sinceEpoch.TotalSeconds + week);
    string stringToSign = HttpUtility.UrlEncode(resourceUri) + "\n" + expiry;
    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key)))
    {
        var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign)));
        var sasToken = String.Format(CultureInfo.InvariantCulture, "SharedAccessSignature sr={0}&sig={1}&se={2}&skn={3}", HttpUtility.UrlEncode(resourceUri), HttpUtility.UrlEncode(signature), expiry, keyName);
        return sasToken;
    }
}

PowerShell

[Reflection.Assembly]::LoadWithPartialName("System.Web")| out-null
$URI="myNamespace.servicebus.windows.net/myEventHub/"
$Access_Policy_Name="RootManageSharedAccessKey"
$Access_Policy_Key="myPrimaryKey"
#Token expires now+300
$Expires=([DateTimeOffset]::Now.ToUnixTimeSeconds())+300
$SignatureString=[System.Web.HttpUtility]::UrlEncode($URI)+ "`n" + [string]$Expires
$HMAC = New-Object System.Security.Cryptography.HMACSHA256
$HMAC.key = [Text.Encoding]::ASCII.GetBytes($Access_Policy_Key)
$Signature = $HMAC.ComputeHash([Text.Encoding]::ASCII.GetBytes($SignatureString))
$Signature = [Convert]::ToBase64String($Signature)
$SASToken = "SharedAccessSignature sr=" + [System.Web.HttpUtility]::UrlEncode($URI) + "&sig=" + [System.Web.HttpUtility]::UrlEncode($Signature) + "&se=" + $Expires + "&skn=" + $Access_Policy_Name
$SASToken

Bash

get_sas_token() {
    local EVENTHUB_URI='EVENTHUBURI'
    local SHARED_ACCESS_KEY_NAME='SHAREDACCESSKEYNAME'
    local SHARED_ACCESS_KEY='SHAREDACCESSKEYVALUE'
    local EXPIRY=${EXPIRY:=$((60 * 60 * 24))} # Default token expiry is 1 day

    local ENCODED_URI=$(echo -n $EVENTHUB_URI | jq -s -R -r @uri)
    local TTL=$(($(date +%s) + $EXPIRY))
    local UTF8_SIGNATURE=$(printf "%s\n%s" $ENCODED_URI $TTL | iconv -t utf8)

    local HASH=$(echo -n "$UTF8_SIGNATURE" | openssl sha256 -hmac $SHARED_ACCESS_KEY -binary | base64)
    local ENCODED_HASH=$(echo -n $HASH | jq -s -R -r @uri)

    echo -n "SharedAccessSignature sr=$ENCODED_URI&sig=$ENCODED_HASH&se=$TTL&skn=$SHARED_ACCESS_KEY_NAME"
}

Autenticar os editores de Centros de Eventos com SAS

Um editor de eventos define um ponto de extremidade virtual para um hub de eventos. O editor só pode ser usado para enviar mensagens a um hub de eventos, não para receber mensagens.

Normalmente, um hub de eventos emprega um editor por cliente. Todas as mensagens enviadas a um dos publicadores de um hub de eventos são enfileiradas nesse hub de eventos. Os editores habilitam o controle de acesso detalhado.

Um token exclusivo é atribuído a cada cliente dos Hubs de Eventos, que é carregado no cliente. Os tokens são produzidos de modo que cada token exclusivo permite acesso a um editor exclusivo diferente. Um cliente que contém um token pode enviar apenas para um editor específico e para nenhum outro. Se vários clientes compartilharem o mesmo token, cada um deles compartilhará o editor.

Chaves SAS são atribuídas a todos os tokens. Normalmente, todos os tokens são assinados com a mesma chave. Os clientes não reconhecem a chave, o que os impede de fabricar tokens. Os clientes operam nos mesmos tokens até expirarem.

Por exemplo, para definir regras de autorização que se limitam a enviar ou publicar apenas para Hubs de Eventos, você precisa definir uma regra de autorização de envio. Você pode criar a regra no nível do namespace ou dar um escopo mais granular para uma entidade específica, como uma instância de hubs de eventos ou um tópico. Um cliente ou aplicação que possui esse acesso granular é chamado de publisher de Event Hubs. Para configurar essa autenticação, siga estes passos:

1. Crie uma chave SAS na entidade para a qual você quer publicar e atribua o escopo de envio a ela. Para obter mais informações, confira Políticas de autorização de acesso compartilhado.

2. Gere um token SAS com tempo de vencimento para um publisher específico usando a chave que você criou na etapa 1. Para o código de exemplo, veja Gerar uma assinatura (token) a partir de uma política.

3. Forneça o token ao cliente publicador, que só pode enviar para a entidade e o publicador aos quais o token concede acesso.

   Quando o token expira, o cliente perde o acesso para enviar ou publicar para a entidade.

Autentice os consumidores de Centros de Eventos com SAS

Para autenticar aplicativos de back-end que consomem dados gerados por produtores de Hubs de Eventos, a autenticação de token dos Hubs de Eventos exige que seus clientes tenham direitos gerenciar ou privilégios escutar atribuídos ao namespace dos Hubs de Eventos, à instância do hub de eventos ou ao tópico. Os dados são consumidos dos Hubs de Eventos usando grupos de consumidores. Embora a política de SAS forneça o escopo granular, esse escopo é definido somente no nível da entidade e não no nível do consumidor. Isso significa que os privilégios definidos no nível do namespace ou na instância ou no nível do tópico do hub de eventos serão aplicados aos grupos de consumidores dessa entidade.

Desabilite a autenticação local ou por chave SAS

Para alguns requisitos de segurança organizacional, talvez você queira desabilitar por completo a autenticação de chave local/SAS e depender da autenticação baseada no Microsoft Entra ID, que é a maneira recomendada de se conectar aos Hubs de Eventos do Azure. Você pode desabilitar a autenticação de chave local/SAS no nível de namespace dos Hubs de Eventos usando o portal do Azure ou modelo do Azure Resource Manager.

Desative a autenticação local ou por chave SAS usando o portal

Você pode desabilitar a autenticação de chave local/SAS para um determinado namespace dos Hubs de Eventos usando o portal do Azure.

1. Acesse seu namespace de Hubs de Eventos no portal do Azure.

2. Na página Visão geral, selecione Habilitada para Autenticação Local, conforme mostrado na imagem a seguir.

   

3. No pop-up Autenticação Local, selecione Desabilitada e OK.

   

Desabilite a autenticação local ou por chave SAS usando um template

Você pode desabilitar a autenticação local para um determinado namespace dos Hubs de Eventos definindo a propriedade disableLocalAuth como true, conforme mostrado no modelo de Azure Resource Manager a seguir (Modelo do ARM).

{
  "apiVersion": "2024-01-01",
  "name": "[parameters('eventHubNamespaceName')]",
  "type": "Microsoft.EventHub/Namespaces",
  "location": "[resourceGroup().location]",
  "sku": {
    "name": "Standard",
    "tier": "Standard"
  },
  "properties": {
    "isAutoInflateEnabled": true,
    "maximumThroughputUnits": 7,
    "disableLocalAuth": true
  },
  "resources": [
    {
      "apiVersion": "2024-01-01",
      "name": "[parameters('eventHubName')]",
      "type": "EventHubs",
      "dependsOn": [
        "[concat('Microsoft.EventHub/namespaces/', parameters('eventHubNamespaceName'))]"
      ],
      "properties": {
        "messageRetentionInDays": "[parameters('messageRetentionInDays')]",
        "partitionCount": "[parameters('partitionCount')]"
      }
    }
  ]
}

Samples

• Confira o exemplo do .NET nº 6 neste local do GitHub para saber como publicar eventos em um hub de eventos usando credenciais de acesso compartilhado ou a identidade de credencial padrão do Azure.
• Confira o exemplo do .NET nº 5 neste local do GitHub para saber como consumir ou processar eventos usando credenciais de acesso compartilhado ou a identidade de credencial padrão do Azure.

Conteúdo relacionado

Agora que você entende a autenticação SAS, explore estes artigos relacionados:

• Autorize o acesso aos recursos dos Centros de Eventos usando assinaturas de acesso compartilhado - Aprenda conceitos de autorização.
• Autorizar o acesso a Hubs de Eventos usando o Microsoft Entra ID - Implementar segurança de nível empresarial.