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

發行項
11/09/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

共用方式為