Conceitos comuns

Este artigo fornece conceitos comuns ao desenvolver aplicações que utilizam a API REST dos Hubs de Notificação do Azure.

Nota

Para garantir um nível mais elevado de segurança, os Notification Hubs desativarão o suporte para as versões TLS 1.0 e 1.1 a 30 de abril de 2020. Para obter mais informações, veja Transport Layer Security (TLS) na documentação dos Hubs de Notificação do Azure.

Analisar cadeia de ligação

Para aceder a um hub de notificação, tem de ter duas informações: o nome do hub e uma cadeia de ligação. A cadeia de ligação contém informações sobre o ponto final do hub e as credenciais de segurança utilizadas para aceder ao mesmo (para SAS, contém um nome de regra e um valor chave).

O código seguinte analisa a cadeia de ligação para extrair as informações relevantes:

public partial class ConnectionStringUtility
{
    public string Endpoint { get; private set; }
    public string SasKeyName { get; private set; }
    public string SasKeyValue { get; private set; }

    public ConnectionStringUtility(string connectionString)
    {
        //Parse Connectionstring
        char[] separator = { ';' };
        string[] parts = connectionString.Split(separator);
        for (int i = 0; i < parts.Length; i++)
        {
            if (parts[i].StartsWith("Endpoint"))
                Endpoint = "https" + parts[i].Substring(11);
            if (parts[i].StartsWith("SharedAccessKeyName"))
                SasKeyName = parts[i].Substring(20);
            if (parts[i].StartsWith("SharedAccessKey"))
                SasKeyValue = parts[i].Substring(16);
        }
    }
}

var parts = connectionString.split(';');
if (parts.length != 3)
throw "Error parsing connection string";

parts.forEach(function(part) {
if (part.indexOf('Endpoint') == 0) {
endpoint = 'https' + part.substring(11);
} else if (part.indexOf('SharedAccessKeyName') == 0) {
sasKeyName = part.substring(20);
} else if (part.indexOf('SharedAccessKey') == 0) {
sasKeyValue = part.substring(16);
}
});

Criar token de segurança SAS

Para se autenticar com SAS, um cliente tem de especificar um token de SAS no cabeçalho Autorização dos pedidos. O token é construído a partir das informações extraídas da cadeia de ligação e do pedido atual que tem de ser autenticado. O token tem o seguinte formulário:

SharedAccessSignature sig=<signature-string>&se=<expiry>&skn=<keyName>&sr=<URL-encoded-resourceURI>

O token refere-se a um keyName (para enviar notificações, normalmente utiliza a propriedade DefaultFullSharedAccessSignature que é criada automaticamente em todos os hubs de notificação).

A assinatura do token de SAS é calculada com o HMAC-SHA256 de um valor de cadeia a sinal com a propriedade PrimaryKey de uma regra de autorização. O valor cadeia a sinal consiste num URI de recurso e numa expiração, formatada da seguinte forma:

StringToSign = <resourceURI> + "\n" + expiry;

Utilize o URI de recurso não codificado para esta operação. O URI do recurso é o URI completo do recurso do Service Bus para o qual o acesso é reivindicado. O formulário é o seguinte:

http://<namespace>.servicebus.windows.net/<hubName>

Por exemplo:

http://contoso.servicebus.windows.net/myHub

A expiração é representada como o número de segundos desde a época 00:00:00 UTC em 1 de janeiro de 1970.

A regra de autorização de acesso partilhado utilizada para assinatura tem de ser configurada na entidade especificada por este URI. No exemplo anterior, o URI é http://contoso.servicebus.windows.net/myHub ou http://contoso.servicebus.windows.net.

O resourceURI codificado por URL tem de ser o mesmo que o URI utilizado na cadeia de carateres a assinar durante o cálculo da assinatura. Deve ser codificado por percentagem e em minúsculas.

O código seguinte, dado um URI de pedido, cria um token de SAS. A versão Java utiliza o Apache Commons Codec e a versão javascript utiliza CryptoJS.

public partial class ConnectionStringUtility
{
    public string getSaSToken(string uri, int minUntilExpire)
    {
        string targetUri = Uri.EscapeDataString(uri.ToLower()).ToLower();

        // Add an expiration in seconds to it.
        long expiresOnDate = DateTime.Now.Ticks / TimeSpan.TicksPerMillisecond;
        expiresOnDate += minUntilExpire * 60 * 1000;
        long expires_seconds = expiresOnDate / 1000;
        String toSign = targetUri + "\n" + expires_seconds;

        // Generate a HMAC-SHA256 hash or the uri and expiration using your secret key.
        MacAlgorithmProvider macAlgorithmProvider = MacAlgorithmProvider.OpenAlgorithm(MacAlgorithmNames.HmacSha256);
        BinaryStringEncoding encoding = BinaryStringEncoding.Utf8;
        var messageBuffer = CryptographicBuffer.ConvertStringToBinary(toSign, encoding);
        IBuffer keyBuffer = CryptographicBuffer.ConvertStringToBinary(SasKeyValue, encoding);
        CryptographicKey hmacKey = macAlgorithmProvider.CreateKey(keyBuffer);
        IBuffer signedMessage = CryptographicEngine.Sign(hmacKey, messageBuffer);

        string signature = Uri.EscapeDataString(CryptographicBuffer.EncodeToBase64String(signedMessage));

        return "SharedAccessSignature sr=" + targetUri + "&sig=" + signature + "&se=" + expires_seconds + "&skn=" + SasKeyName;
    }
}

var getSelfSignedToken = function(targetUri, sharedKey, ruleId,
expiresInMins) {
targetUri = encodeURIComponent(targetUri.toLowerCase()).toLowerCase();

// Set expiration in seconds
var expireOnDate = new Date();
expireOnDate.setMinutes(expireOnDate.getMinutes() + expiresInMins);
var expires = Date.UTC(expireOnDate.getUTCFullYear(), expireOnDate
.getUTCMonth(), expireOnDate.getUTCDate(), expireOnDate
.getUTCHours(), expireOnDate.getUTCMinutes(), expireOnDate
.getUTCSeconds()) / 1000;
var tosign = targetUri + '\n' + expires;

// using CryptoJS
var signature = CryptoJS.HmacSHA256(tosign, sharedKey);
var base64signature = signature.toString(CryptoJS.enc.Base64);
var base64UriEncoded = encodeURIComponent(base64signature);

// construct autorization string
var token = "SharedAccessSignature sr=" + targetUri + "&sig="
+ base64UriEncoded + "&se=" + expires + "&skn=" + ruleId;
// console.log("signature:" + token);
return token;
};