使用 OAuth 2.0 JSON Web 令牌 (JWT) 進行命名空間的驗證

本文說明如何使用 OAuth 2.0 JSON Web 令牌向 Azure 事件方格命名空間進行驗證。

Azure Event Grid 的 MQTT 訊息代理程式支援 OAuth 2.0 JWT 驗證，可讓用戶端使用任何識別提供者所簽發的 JSON Web 令牌，使用事件方格命名空間進行連線和驗證，除了Microsoft Entra ID 之外。

必要條件

若要針對命名空間使用 OAuth 2.0 JWT 驗證，您必須具備下列必要條件：

可發出 JSON Web 令牌的識別提供者。
CA 憑證，其中包含用來驗證用戶端令牌（Key Vault）的您的公鑰，或您公鑰憑證的 PEM 檔案（直接上傳）。

高階步驟

若要針對命名空間使用 OAuth 2.0 JWT 驗證，請遵循下列步驟：

建立命名空間並設定其子資源。
在事件方格命名空間上啟用受控識別。
遵循下列步驟，在事件方格命名空間上設定 OAuth 2.0 驗證設定：
1. 建立 Azure Key Vault 帳戶，此帳戶會裝載包含公鑰的 CA 憑證，並在 Key Vault 中新增命名空間受控識別的角色指派。
2. 或將公鑰憑證的 PEM 檔案上傳至命名空間。
用戶端可以使用識別提供者所提供的權杖，連線到事件方格命名空間。

建立命名空間並設定其子資源

遵循快速入門：使用 Azure 入口網站在事件方格命名空間上發佈和訂閱 MQTT 訊息中的指示，建立命名空間並設定其子資源。當用戶端身分識別來自提供的權杖時，請略過憑證和用戶端建立步驟。客戶端屬性是基於客戶端標記中的自訂宣告。用戶端屬性用於用戶端群組查詢、主題範本變數和路由擴充設定中。

在事件方格命名空間上啟用受控識別

命名空間會使用受控識別來存取 Azure Key Vault 執行個體，為自訂網域取得伺服器憑證。請使用下列命令，在事件方格命名空間上啟用系統指派的受控識別：

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

如需使用 Azure 入口網站設定系統和使用者指派身分識別的相關資訊，請參閱啟用事件方格命名空間的受控識別。

在事件方格命名空間 -Key 保存庫上設定 OAuth 2.0 JWT 驗證設定

首先，建立 Azure Key Vault 帳戶、上傳您的伺服器證書，並將命名空間的受控識別指派給密鑰保存庫的適當角色。然後，您可以使用 Azure 入口網站或 Azure CLI 在事件方格命名空間上設定自訂驗證設定。您必須先建立命名空間，然後使用下列步驟將其更新。

建立 Azure Key Vault 帳戶並上傳伺服器憑證

請使用下列命令來建立 Azure Key Vault 帳戶：

az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseuap"

使用下列命令將憑證匯入至 Azure Key Vault
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
附註

您的憑證必須在 DNS 的主體別名中包含網域名稱。如需詳細資訊，請參閱教學課程：在 Azure Key Vault 中匯入憑證。

在 Azure Key Vault 中為命名空間的受控識別新增角色指派

您必須提供命名空間的存取權，才能使用下列步驟來存取 Azure Key Vault 帳戶：

使用下列命令取得事件方格命名空間系統受控識別主體識別碼

$principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv)

取得 Azure Key Vault 資源識別碼。

$keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv)

在 Key Vault 中為命名空間的受控識別新增角色指派。
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
如需 Key Vault 存取和入口網站體驗的詳細資訊，請參閱透過 Azure 角色型存取控制，提供 Key Vault 金鑰、憑證和祕密的存取權。

使用 Azure 入口網站設定驗證

在 Azure 入口網站中，瀏覽到您的事件方格命名空間。
在 [事件方格命名空間] 頁面上，選取左側功能表上的 [設定]。
在 [自訂 JWT 驗證] 區段中，指定下列屬性的值：
1. 選取 [啟用自訂 JWT 驗證]。
2. 令牌簽發者：輸入 MQTT 用戶端所呈現之 JWT 簽發者宣告的值。
3. 針對 簽發者憑證，選取 來自 Azure Key Vault。
4. 在新的頁面中，指定下列屬性的值。
  1. 憑證 URL：Azure Key Vault 中您所建立簽發者憑證的憑證識別碼。您可以改為選擇 [使用金鑰保存庫選取憑證]，從您的訂用帳戶選取憑證和金鑰保存庫。
  2. 身分識別：用來搭配 Key Vault 進行驗證的身分識別，用來存取已建立的簽發者憑證。
  3. 選取 [新增]。
回到 [設定] 頁面上，選取 [套用]。

附註

您最多可以基於憑證/金鑰輪替目的新增兩個 iss 憑證。

使用 Azure CLI

使用下列命令，搭配自訂 JWT 驗證設定來更新命名空間。

az resource update \
  --resource-type Microsoft.EventGrid/namespaces \
  --api-version 2024-06-01-preview \
  --ids /subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.EventGrid/namespaces/sample-namespace \
  --set properties.topicSpacesConfiguration.clientAuthentication='{
    \"customJwtAuthentication\":{
      \"tokenIssuer\":\"sample-issuer\",
      \"issuerCertificates\":[
        {
          \"certificateUrl\":\"https://sample-vault.vault.azure.net/certificates/sample-cert/12345abcdef67890\",
          \"identity\":{
            \"type\":\"UserAssigned\",
            \"userAssignedIdentity\":\"/subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/sample-identity\"
          }
        }
      ]
    }
  }'

JSON Web Token 格式

JSON Web 令牌必須具有 JWT 標頭、JWT 承載和 JWT 簽章區段。

JWT 標頭

標頭必須至少包含 typ 和 alg 欄位。  typ 必須一律為 JWS，而 alg 必須一律為 RS256。權杖標頭必須如下所示：

{
    "typ": "JWT",
    "alg": "RS256"
}

JWT 承載

事件方格需要下列宣告：iss、sub、aud、exp、nbf。

名稱	描述
`iss`	發行者。 JWT 中的值必須符合事件方格命名空間設定中的簽發者，才能進行自訂 JWT 驗證。
`sub`	主旨。值會用作驗證身分識別名稱。
`aud`	觀眾。值是字串陣列。值必須包含該事件方格命名空間的標準事件方格命名空間主機名稱和/或自訂網域 (如果已設定)。對象可以包含其他字串，但我們需要其中至少一個字串成為此命名空間的標準事件方格命名空間主機名稱或自訂網域。
`exp`	到期。 JWT 到期的 Unix 時間。
`nbf`	生效時間。 JWT 生效的單位時間。

如果事件方格具有下列其中一種類型，則其會將所有宣告對應至用戶端屬性：int32、string、array of strings。標準宣告 iss、sub、aud、exp、nbf 排除在客戶端屬性之外。在下列 JWT 範例中，只有三個宣告 (num_attr、str_attr、str_list_attr) 會轉換成用戶端屬性，因為其具有正確的類型 int32、string、array of strings。  incorrect_attr_1、incorrect_attr_2、incorrect_attr_3 不會轉換成用戶端屬性，因為其具有類型錯誤：float、array of integers、object。

{
    "iss": "correct_issuer",
    "sub": "d1",
    "aud": "testns.mqtt-broker-int.azure.net",
    "exp": 1712876224,
    "nbf": 1712869024,
    "num_attr": 1,
    "str_attr": "some string",
    "str_list_attr": [
        "string 1",
        "string 2"
    ],
    "incorrect_attr_1": 1.23,
    "incorrect_attr_2": [
        1,
        2,
        3
    ],
    "incorrect_attr_3": {
        "field": "value"
    }
}

在事件方格命名空間上設定 OAuth 2.0 JWT 驗證設定 - 直接上傳

在此步驟中，您會使用 Azure 入口網站和 Azure CLI，在事件方格命名空間上設定自定義 JWT 驗證設定。您必須先建立命名空間，然後使用下列步驟將其更新。

使用 Azure 入口網站

在 Azure 入口網站中瀏覽至您的事件方格命名空間。
在 [事件方格命名空間] 頁面上，選取左側功能表上的 [組態]。
在 [自定義 JWT 驗證] 區段中，指定下列屬性的值：
1. 選取 [啟用自訂 JWT 驗證]。
2. 令牌簽發者：輸入 MQTT 用戶端所呈現之 JWT 簽發者宣告的值。
3. 選取 [簽發者憑證] 選項 – [直接上傳]。
在新的頁面中，指定下列屬性的值。
1. 憑證：以 PEM 格式上傳您的伺服器證書。
2. 兒童：憑證的唯一密鑰標識碼。
3. 選取 [新增]。
回到 [設定] 頁面上，選取 [套用]。

使用 Azure CLI

使用下列命令，以 OAuth 2.0 JWT 驗證組態更新命名空間。

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2024-12-15-preview \ 
    --set customJwtAuthenticationSettings='{ 
        "tokenIssuer": "issuer-name", 
        "encodedIssuerCertificates": [
            { 
                "kid": "key1", 
                "encodedCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-in-PEM-format>\n-----END CERTIFICATE-----" 
            } 
        ] 
    }

以您的實際值取代 <resource-group-name>、 <namespace-name>、 <location>、 <key-vault-name>、 <certificate-name>和 <certificate-in-PEM-format> 。
encodedCertificate 值必須包含 PEM 格式的完整憑證和公鑰，包括標頭（ "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----）。
請確定提供的公鑰憑證是有效且由您的識別提供者信任的。
如果憑證已輪替或過期，請定期更新編碼的發行者憑證。

JSON Web Token 格式

JSON Web 令牌必須具有 JWT 標頭、JWT 承載和 JWT 簽章區段。

事件方格需要下列宣告：iss、sub、aud、exp、nbf。

kid 是選擇性的。如果存在，則會使用具有與 kid 匹配的憑證進行驗證。
未用作屬性的標準宣告清單 - iss, sub, aud, exp, nbf, iat, jti
所有具有正確數據類型的宣告（符合 int32 的數字、字串、字串陣列）都會被用作屬性。在範例num_attr_pos中，、 num_attr_negstr_attrstr_list_attr 宣告具有正確的數據類型，並做為屬性使用。
在範例bool_attr中，num_attr_to_big、 num_attr_floatobj_attr 宣告的數據類型不正確，而且不會當做屬性使用。

{ 
  "typ": "JWT", 
  "alg": "RS256", 
  "kid": "keyId1" 
}.{ 
  "iss": "some-issuer", 
  "sub": "device1", 
  "aud": "event-grid-namespace.ts.eventgrid.azure.net", 
  "exp": 1770426501, 
  "nbf": 1738886901, 
  "bool_attr": true, 
  "num_attr_pos": 1, 
  "num_attr_neg": -1, 
  "num_attr_to_big": 9223372036854775807, 
  "num_attr_float": 1.23, 
  "str_attr": "str_value", 
  "str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
  ], 
  "obj_attr": { 
      "key": "value" 
  } 
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-05

共用方式為

使用 OAuth 2.0 JSON Web 令牌 (JWT) 進行命名空間的驗證

必要條件

高階步驟

建立命名空間並設定其子資源

在事件方格命名空間上啟用受控識別

在事件方格命名空間 -Key 保存庫上設定 OAuth 2.0 JWT 驗證設定

建立 Azure Key Vault 帳戶並上傳伺服器憑證

在 Azure Key Vault 中為命名空間的受控識別新增角色指派

使用 Azure 入口網站設定驗證

使用 Azure CLI

JSON Web Token 格式

JWT 標頭

JWT 承載

在事件方格命名空間上設定 OAuth 2.0 JWT 驗證設定 - 直接上傳

使用 Azure 入口網站

使用 Azure CLI

JSON Web Token 格式

相關內容

意見反應

其他資源