Autenticar clientes da Grade de Eventos do Azure usando chaves de acesso ou assinaturas de acesso compartilhado (versão prévia)

Este artigo fornece informações sobre como autenticar clientes nos Tópicos do Namespace de Eventos do Azure, tópicos personalizados, domínios e namespaces de parceiros usando um token de chave de acesso ou token SAS (Assinatura de Acesso Compartilhado).

Autenticar usando uma chave de acesso

A autenticação de chave de acesso é a forma mais simples de autenticação. Você pode passar a chave de acesso como um cabeçalho HTTP ou um parâmetro de consulta de URL.

Chave de acesso em um cabeçalho HTTP

Passe a chave de acesso como um valor para o cabeçalho HTTP: aeg-sas-key.

aeg-sas-key: XXXXXXXXXXXXXXXXXX0GXXX/nDT4hgdEj9DpBeRr38arnnm5OFg==

Chave de acesso como um parâmetro de consulta

Você também pode especificar aeg-sas-key como um parâmetro de consulta.

Por exemplo, para tópicos de namespace, essa é a aparência que sua URL de solicitação HTTP poderia ter passando uma chave como um parâmetro.

https://<namespace_name>.<region>.eventgrid.azure.net/topics/<topic_name>:publish?aeg-sas-key=XXXXXXXX53249XX8XXXXX0GXXX/nDT4hgdEj9DpBeRr38arnnm5OFg==

Para tópicos personalizados, domínios e namespaces de parceiro, sua URL de solicitação HTTP deve ser semelhante à seguinte:

https://<yourtopic>.<region>.eventgrid.azure.net/api/events?aeg-sas-key=XXXXXXXX53249XX8XXXXX0GXXX/nDT4hgdEj9DpBeRr38arnnm5OFg==

Assinaturas de Acesso Compartilhado

As SAS (Assinaturas de Acesso Compartilhado) fornecem controle de acesso sobre os recursos com os quais os clientes podem se comunicar. Aqui estão alguns dos controles que você pode definir em uma SAS:

• Defina uma hora de expiração de SAS. Esse valor define efetivamente o intervalo no qual a SAS é válida pode ser usada para autenticação.
• O recurso para o qual uma SAS pode ser usada. O token SAS pode ser criado para acessar tópicos personalizados, domínios, namespaces de parceiro e namespaces. Se você criar uma SAS para um tópico personalizado, domínio ou namespace de parceiro, um cliente poderá usá-la para publicar eventos em qualquer um desses recursos. Ao criar uma SAS para recursos de namespace, você tem controle granular sobre o que um cliente pode acessar. Se você criar uma SAS cujo recurso é um namespace, um cliente poderá publicar eventos em qualquer tópico de namespace dentro do namespace e poderá receber eventos de qualquer assinatura de evento em qualquer um dos tópicos do namespace. Da mesma forma, quando você cria uma SAS para um tópico de namespace, um cliente pode publicar eventos nesse tópico de namespace e receber eventos de qualquer assinatura de evento nesse tópico. Quando uma SAS é criada para uma assinatura de evento, o cliente pode receber eventos por meio dessa assinatura de evento.
• Somente os clientes que apresentam uma SAS válida podem enviar ou receber dados para a Grade de Eventos.

Token SAS (Assinatura de Acesso Compartilhado)

Você pode gerar um token SAS que será incluído quando seu aplicativo cliente se comunicar com a Grade de Eventos. Tokens SAS para recursos da Grade de Eventos são cadeias de caracteres codificadas URL com o seguinte formato: r={resource}&e={expiration_utc}&s={signature}.

• {resource} é a URL que representa o recurso da Grade de Eventos que o cliente acessa.
  • O formato de URL válido para tópicos personalizados, domínios e namespaces de parceiro é https://<yourtopic>.<region>.eventgrid.azure.net/api/events.
  • O formato válido para recursos de namespace é o seguinte:
    • Namespaces: https://<namespace-name>.<region>.eventgrid.azure.net
    • Tópicos de namespace: https://<namespace_name>.<region>.eventgrid.azure.net/topics/<topic_name>
    • Assinaturas de evento: https://<namespace_name>.<region>.eventgrid.azure.net/topics/<topic_name>/eventsubscriptions/<event_subscription_name>
• {expiration_utc} é a hora de expiração UTC codificada da URL da SAS.
• O {signature} é o hash SHA-256 calculado no URI do recurso e a representação de cadeia de caracteres do instante de expiração do token, separados por CRLF. O cálculo de hash é semelhante ao seguinte pseudocódigo e retorna um valor de hash de 256 bits/32 bytes.

SHA-256('https://<namespace_name>.eventgrid.azure.net/'+'\n'+ 1438205742)

O token contém os valores não hash para que o destinatário (Grade de Eventos) possa recalcular o hash com os mesmos parâmetros, verificando se o token não foi modificado (integridade de dados).

Um token SAS é válido para todos os recursos prefixados com o URI do recurso usado na cadeia de caracteres de assinatura.

Para consultar todas as versões de API com suporte ao usar a Grade de Eventos, consulte tipos de recurso Microsoft.EventGrid.

Autenticar usando SAS

Seu aplicativo pode se autenticar antes de um recurso da Grade de Eventos apresentando um token SAS. Isso pode ser feito usando o cabeçalho aeg-sas-token ou o cabeçalho Authorization SharedAccessSignature com uma solicitação HTTP. As seções a seguir descrevem a maneira de gerar um token SAS e como usá-lo quando seu aplicativo cliente faz solicitações HTTP para enviar ou receber eventos (entrega por pull).

Gerar um token SAS programaticamente

Os seguintes exemplos de C# e Python mostram como criar um token SAS para uso com a Grade de Eventos:

Exemplo de C#

static string BuildSharedAccessSignature(string resource, DateTime expirationUtc, string key)
{
    const char Resource = 'r';
    const char Expiration = 'e';
    const char Signature = 's';

    string encodedResource = HttpUtility.UrlEncode(resource);
    var culture = CultureInfo.CreateSpecificCulture("en-US");
    var encodedExpirationUtc = HttpUtility.UrlEncode(expirationUtc.ToString(culture));

    string unsignedSas = $"{Resource}={encodedResource}&{Expiration}={encodedExpirationUtc}";
    using (var hmac = new HMACSHA256(Convert.FromBase64String(key)))
    {
        string signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(unsignedSas)));
        string encodedSignature = HttpUtility.UrlEncode(signature);
        string signedSas = $"{unsignedSas}&{Signature}={encodedSignature}";

        return signedSas;
    }
}

Exemplo de Python

def generate_sas_token(uri, key, expiry=3600):
    ttl = datetime.datetime.utcnow() + datetime.timedelta(seconds=expiry)
    encoded_resource = urllib.parse.quote_plus(uri)
    encoded_expiration_utc = urllib.parse.quote_plus(ttl.isoformat())

    unsigned_sas = f'r={encoded_resource}&e={encoded_expiration_utc}'
    signature = b64encode(HMAC(b64decode(key), unsigned_sas.encode('utf-8'), sha256).digest())
    encoded_signature = urllib.parse.quote_plus(signature)
    
    token = f'r={encoded_resource}&e={encoded_expiration_utc}&s={encoded_signature}'

    return token

Usando o cabeçalho aeg-sas-token

Aqui está um exemplo que mostra como passar um token SAS como um valor para o cabeçalho aeg-sas-token.

aeg-sas-token: r=https%3a%2f%2fmytopic.eventgrid.azure.net%2fapi%2fevents&e=6%2f15%2f2017+6%3a20%3a15+PM&s=XXXXXXXXXXXXX%2fBPjdDLOrc6THPy3tDcGHw1zP4OajQ%3d

Usando o cabeçalho Authorization

Este exemplo mostra como passar um token SAS como um valor para o cabeçalho Authorization.

Authorization: SharedAccessSignature r=https%3a%2f%2fmytopic.eventgrid.azure.net%2fapi%2fevents&e=6%2f15%2f2017+6%3a20%3a15+PM&s=XXXXXXXXXXXXX%2fBPjdDLOrc6THPy3tDcGHw1zP4OajQ%3d

Próximas etapas

• Envie eventos para o seu tópico personalizado.
• Publicar eventos em tópicos de namespace usando Java
• Receber eventos usando a entrega por pull com Java