使用存取金鑰或共用存取簽章，驗證 Azure 事件方格用戶端 (預覽)

發行項
05/21/2024

本文提供有關使用存取金鑰或共用存取簽章 (SAS) 權杖，向 Azure 事件命名空間主題、自訂主題、網域和合作夥伴命名空間驗證用戶端的資訊。

重要

使用 Microsoft Entra 身分識別驗證和授權使用者或應用程式，可透過金鑰型和共用存取簽章 (SAS)，提供更佳安全性和方便使用度。使用 Microsoft Entra ID 不需要冒著潛在安全性弱點的風險，在程式碼中儲存用於驗證的祕密。強烈建議您使用 Microsoft Entra ID 搭配您的應用程式。

使用存取金鑰進行驗證

存取金鑰驗證是最簡單的驗證方法。您能將存取金鑰當作 HTTP 標頭或 URL 查詢參數傳遞。

HTTP 標頭中的存取金鑰

將存取金鑰當作 HTTP 標頭的值傳遞：aeg-sas-key。

aeg-sas-key: XXXXXXXXXXXXXXXXXX0GXXX/nDT4hgdEj9DpBeRr38arnnm5OFg==

存取金鑰當作查詢參數

您也可以指定 aeg-sas-key 作為查詢參數。

例如，對於命名空間主題，這是 HTTP 要求 URL 似乎可將金鑰當做參數傳遞的方式。

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

對於自訂主題、網域和合作夥伴命名空間，您的 HTTP 要求 URL 看起來應該如下所示：

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

共用存取簽章

共用存取簽章 (SAS) 可讓您對用戶端可與其通訊的資源進行存取控制。以下是您可以在 SAS 中設定的一些控制項：

設定 SAS 到期時間。此值有效地定義可用於驗證的 SAS 有效間隔。
可以使用 SAS 的資源。您可以建立 SAS 權杖來存取自訂主題、網域、合作夥伴命名空間和命名空間。如果您為自訂主題、網域或夥伴命名空間建立了 SAS，用戶端可以使用此 SAS，將事件發佈至其中任一個資源。當您為命名空間資源建立 SAS 時，您可以精細地控制用戶端可以存取的內容。如果您建立其資源為命名空間的 SAS，用戶端可以將事件發佈至命名空間內的任何命名空間主題，而且可以從任何命名空間主題上的任何事件訂用帳戶接收事件。同樣地，當您為命名空間主題建立 SAS 時，用戶端可以將事件發佈至該命名空間主題，並從該主題上的任何事件訂用帳戶接收事件。為事件訂用帳戶建立 SAS 時，用戶端可以透過該事件訂用帳戶接收事件。
只有呈現有效 SAS 的用戶端才能將資料傳送至事件方格或從中接收資料。

共用存取簽章權杖

您可以產生要在您用戶端應用程式與事件方格通訊時包含的 SAS 權杖。事件方格資源的 SAS 權杖是具有下列格式的 URL 編碼字串：r={resource}&e={expiration_utc}&s={signature}。

{resource} 是代表用戶端所存取事件方格資源的 URL。
- 自訂主題、網域和夥伴命名空間的有效 URL 格式為 https://<yourtopic>.<region>.eventgrid.azure.net/api/events。
- 命名空間資源的有效格式如下：
  - 命名空間：https://<namespace-name>.<region>.eventgrid.azure.net
  - 命名空間主題：https://<namespace_name>.<region>.eventgrid.azure.net/topics/<topic_name>
  - 事件訂用帳戶：https://<namespace_name>.<region>.eventgrid.azure.net/topics/<topic_name>/eventsubscriptions/<event_subscription_name>
{expiration_utc} 是 SAS 的 URL 編碼 UTC 到期時間。
{signature} 是針對資源 URI 和權杖到期時間的字串表示法 (以 CRLF 分隔) 計算的 SHA-256 雜湊。雜湊計算看起來類似下列虛擬程式碼，會傳回 256 位元/32 位元組的雜湊值。

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

權杖會包含非雜湊值，以便接收者 (事件方格) 可以使用相同的參數重新計算雜湊，從而驗證是否尚未修改權杖 (資料完整性)。

SAS 權杖適用於以簽章字串中所使用的資源 URI 作為前置詞的所有資源。

若要在使用事件方格時諮詢所有支援的 API 版本，請參閱 Microsoft.EventGrid 資源類型。

使用 SAS 進行驗證

您的應用程式可以藉由呈現 SAS 權杖，在事件方格資源之前進行驗證。這可以使用 aeg-sas-token 標頭或 Authorization SharedAccessSignature 標頭搭配 HTTP 要求來完成。下列各節描述如何產生 SAS 權杖的方式，以及如何在用戶端應用程式提出 HTTP 要求，來傳送或接收 (提取傳遞) 事件時使用該權杖。

以程式設計方式產生 SAS 權杖

下列 C# 和 Python 範例為您說明如何建立 SAS 權杖，以搭配事件方格使用：

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

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

使用 aeg-sas-token 標頭

以下範例說明如何將 SAS 權杖作為 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

使用授權標頭

此範例說明如何將 SAS 權杖作為 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

共用方式為