Merge pull request #299108 from spelluru/egridprebuild0430

Event Grid - Pre Build updates

Author: JillGrant615

articles/event-grid/authenticate-with-namespaces-using-json-web-tokens.md

@@ -3,34 +3,33 @@ title: Authenticate with namespaces using JSON Web Tokens
 description: This article shows you how to authenticate with Azure Event Grid namespace using JSON Web Tokens.
 ms.topic: how-to
 ms.custom: build-2024, devx-track-azurecli
-ms.date: 01/27/2025
+ms.date: 04/30/2025
 author: Connected-Seth
 ms.author: seshanmugam
 ---
 
-# Authenticate with namespaces using JSON Web Tokens
-This article shows how to authenticate with Azure Event Grid namespace using JSON Web Tokens.
+# Use OAuth 2.0 JSON Web Tokens (JWT) to authenticate with namespaces
+This article shows how to authenticate with Azure Event Grid namespace using OAuth 2.0 JSON Web Tokens. 
 
-Azure Event Grid's MQTT broker supports custom JWT authentication, which enables clients to connect and authenticate with an Event Grid namespace using JSON Web Tokens that are issued by any identity provider, aside from Microsoft Entra ID. 
+Azure Event Grid's MQTT broker supports OAuth 2.0 JWT authentication, which enables clients to connect and authenticate with an Event Grid namespace using JSON Web Tokens that are issued by any identity provider, aside from Microsoft Entra ID. 
 
 ## Prerequisites 
 
-To use custom JWT authentication for namespaces, you need to have the following prerequisites: 
+To use OAuth 2.0 JWT authentication for namespaces, you need to have the following prerequisites: 
 
 - Identity provider that can issue JSON Web Tokens. 
-- CA certificate that includes your public keys used to validate the client tokens. 
-- Azure Key Vault account to host the CA certificate that includes your public keys. 
+- CA certificate that includes your public keys used to validate the client tokens(Key Vault) or PEM file of your public key certificates(direct upload). 
 
 ## High-level steps 
 
-To use custom JWT authentication for namespaces, follow these steps: 
+To use OAuth 2.0 JWT authentication for namespaces, follow these steps: 
 
-1. Create a namespace and configure its subresources.
+1. Create a namespace and configure its subresources. 
 1. Enable managed identity on your Event Grid namespace. 
-1. Create an Azure Key Vault account that hosts the CA certificate that includes your public keys. 
-1. Add role assignment in Azure Key Vault for the namespace’s managed identity. 
-1. Configure custom authentication settings on your Event Grid namespace 
-1. Your clients can connect to the Event Grid namespace using the tokens provided by your identity provider. 
+1. Configure OAuth 2.0 authentication settings on your Event Grid namespace by following these steps: 
+    1. Create an Azure Key Vault account that hosts the CA certificate that includes your public keys and  add role assignment in Key Vault for the namespace’s managed identity. 
+    1. Upload the PEM file of your public key certificates to namespace. 
+  1. Your clients can connect to the Event Grid namespace using the tokens provided by your identity provider. 
 
 ## Create a namespace and configure its subresources 
 Follow instructions from [Quickstart: Publish and subscribe to MQTT messages on Event Grid Namespace with Azure portal](mqtt-publish-and-subscribe-portal.md) to create a namespace and configure its subresources. Skip the certificate and client creation steps as the client identities come from the provided token. Client attributes are based on the custom claims in the client token. The client attributes are used in the client group query, topic template variables, and routing enrichment configuration.
@@ -44,7 +43,11 @@ az eventgrid namespace update --resource-group <resource group name> --name <nam
 
 For information configuring system and user-assigned identities using the Azure portal, see [Enable managed identity for an Event Grid namespace](event-grid-namespace-managed-identity.md).
 
-## Create an Azure Key Vault account and upload your server certificate 
+
+## Configure OAuth 2.0 JWT authentication settings on your Event Grid namespace -Key Vault 
+First, create an Azure Key Vault account, upload your server certificate, and assign the namespace's managed identity an appropriate role on the key vault. Then, you configure custom authentication settings on your Event Grid namespace using Azure portal and Azure CLI. You need to create the namespace first then update it using the following steps.
+
+### Create an Azure Key Vault account and upload your server certificate 
 
 1. Use the following command to create an Azure Key Vault account: 
 
@@ -60,7 +63,7 @@ For information configuring system and user-assigned identities using the Azure
     > Your certificate must include the domain name in the Subject Alternative name for DNS. For more information, see [Tutorial: Import a certificate in Azure Key Vault](/azure/key-vault/certificates/tutorial-import-certificate).
 
 
-## Add role assignment in Azure Key Vault for the namespace’s managed identity 
+### Add role assignment in Azure Key Vault for the namespace’s managed identity 
 You need to provide access to the namespace to access your Azure Key Vault account using the following steps: 
 
 1. Get Event Grid namespace system managed identity principal ID using the following command 
@@ -81,19 +84,17 @@ You need to provide access to the namespace to access your Azure Key Vault accou
 
     For more information about Key Vault access and the portal experience, see [Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control](/azure/key-vault/general/rbac-guide). 
 
-## Configure custom authentication settings on your Event Grid namespace 
-In this step, you configure custom authentication settings on your Event Grid namespace using Azure portal and Azure CLI. You need to create the namespace first then update it using the following steps.
 
-### Use Azure portal
+### Use Azure portal to configure authentication
 
 1. Navigate to your Event Grid namespace in the [Azure portal](https://portal.azure.com).
 1. On the **Event Grid Namespace** page, select **Configuration** on the left menu. 
 1. In the **Custom JWT authentication** section, specify values for the following properties:  
     1. Select **Enable custom JWT authentication**. 
     1. **Token Issuer**: Enter the value of the issuer claims of the JWTs, presented by the MQTT clients. 
-    1. Select **Add issuer certificate**
+    1. For **Issuer certificate**, select **From Azure Key Vault**. 
     
-        :::image type="content" source="./media/authenticate-with-namespaces-using-json-web-tokens/configuration-custom-authentication.png" alt-text="Screenshot that shows the Custom JWT authentication section of the Configuration page for an Event Grid namespace." lightbox="./media/authenticate-with-namespaces-using-json-web-tokens/configuration-custom-authentication.png":::
+        :::image type="content" source="./media/authenticate-with-namespaces-using-json-web-tokens/select-azure-key-vault-option.png" alt-text="Screenshot that shows the selection of the Azure Key Vault option of the Configuration page for an Event Grid namespace." lightbox="./media/authenticate-with-namespaces-using-json-web-tokens/select-azure-key-vault-option.png":::
     1. In the new page, specify values for the following properties.
         1. **Certificate URL**: the Certificate Identifier of the issuer certificate in Azure Key Vault that you created. You can choose **Select a certificate using a key vault** instead to select the certificate and the key vault from your subscriptions. 
         1. **Identity**: the identity used to authenticate with the Key Vault to access the issuer certificate that was created.          
@@ -130,7 +131,7 @@ az resource update \
   }'
  
 ```
-## JSON Web Token format
+### JSON Web Token format
 JSON Web Tokens are divided into the JWT Header and JWT payload sections.
 
 ### JWT Header 
@@ -184,6 +185,92 @@ Event Grid maps all claims to client attributes if they have one of the followin
 }
 ```
 
+## Configure OAuth 2.0 JWT authentication settings on your Event Grid namespace - Direct upload 
+
+In this step, you configure custom JWT authentication settings on your Event Grid namespace using Azure portal and Azure CLI. You need to create the namespace first then update it using the following steps. 
+
+### Use Azure portal
+1. Navigate to your Event Grid namespace in the Azure portal. 
+1. On the Event Grid Namespace page, select Configuration on the left menu. 
+1. In the Custom JWT authentication section, specify values for the following properties: 
+    1. Select **Enable custom JWT authentication**. 
+    1. **Token Issuer**: Enter the value of the issuer claims of the JWTs, presented by the MQTT clients. 
+    1. Select  issuer certificate option – **Direct Upload**.  
+
+        :::image type="content" source="./media/authenticate-with-namespaces-using-json-web-tokens/direct-upload-option.png" alt-text="Screenshot that shows the selection of the Direct Upload option of the Configuration page for an Event Grid namespace." lightbox="./media/authenticate-with-namespaces-using-json-web-tokens/direct-upload-option.png":::
+1. In the new page, specify values for the following properties. 
+    1. **Certificate**: upload your server certificate in PEM Format. 
+    1. **Kid**: A unique key identifier for the certificate. 
+    1. Select **Add**. 
+    
+        :::image type="content" source="./media/authenticate-with-namespaces-using-json-web-tokens/upload-certificate.png" alt-text="Screenshot that shows the Upload issuer certificate page." lightbox="./media/authenticate-with-namespaces-using-json-web-tokens/upload-certificate.png":::
+1. Back on the **Configuration** page, select **Apply**. 
+
+
+### Use Azure CLI 
+Use the following command to update your namespace with the OAuth 2.0 JWT authentication configuration. 
+
+```azurecli
+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-----" 
+            } 
+        ] 
+    } 
+```
+
+- Replace `<resource-group-name>`, `<namespace-name>`, `<location>`, `<key-vault-name>`, `<certificate-name>`, and `<certificate-in-PEM-format>` with your actual values. 
+- The encodedCertificate value must include the full certificate in PEM format, including headers ( `"-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE----`). 
+- Ensure the public key certificate provided is valid and trusted by your identity provider. 
+- Regularly update the encodedIssuerCertificates if certificates are rotated or expired. 
+
+### JSON Web Token format
+
+JWT payload 
+
+Event Grid requires the following claims: `iss`, `sub`, `aud`, `exp`, `nbf`. 
+
+* `kid` is optional. If it is present, then certificate with matching `kid` is used for validation. 
+* List of standard claims that aren't used as attributes - `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`. 
+* All claims which have correct data type (number that fits int32, string, array of strings) are used as attributes. In the example `num_attr_pos`, `num_attr_neg`, `str_attr`, `str_list_attr` claims have correct data types and are used as attributes. 
+* In the example `bool_attr`, `num_attr_to_big`, `num_attr_float`, `obj_attr` claims have incorrect data types and aren't be used as attributes. 
+
+ 
+```json
+{ 
+  "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" 
+  } 
+} 
+```
+
+
 ## Related content
 - [MQTT client authentication](mqtt-client-authentication.md)
 - [Authenticate client using custom JWT](mqtt-client-custom-jwt.md)

articles/event-grid/media/authenticate-with-namespaces-using-json-web-tokens/configuration-custom-authentication.png

@@ -15,19 +15,21 @@ Azure Event Grid's MQTT broker supports the following authentication modes.
 
 - Certificate-based authentication
 - Microsoft Entra ID authentication
-- Custom JWT authentication
+- OAuth 2.0 (JSON Web Token) authentication 
 
 ## Certificate-based authentication
 You can use Certificate Authority (CA) signed certificates or self-signed certificates to authenticate clients. For more information, see [MQTT Client authentication using certificates](mqtt-client-certificate-authentication.md).
 
 ## Microsoft Entra ID authentication
 You can authenticate MQTT clients with Microsoft Entra JWT to connect to Event Grid namespace. You can use Azure role-based access control (Azure RBAC) to enable MQTT clients, with Microsoft Entra identity, to publish or subscribe access to specific topic spaces. For more information, see [Microsoft Entra JWT authentication and Azure RBAC authorization to publish or subscribe MQTT messages](mqtt-client-microsoft-entra-token-and-rbac.md). 
 
-## Custom JWT authentication
-You can authenticate MQTT clients  using JSON Web Tokens (JWT) issued by any third-party OpenID Connect (OIDC) identity provider. This authentication method provides a lightweight, secure, and flexible option for MQTT clients that aren't provisioned in Azure. For more information, see [authenticate client using custom JWT](mqtt-client-custom-jwt.md)
+## OAuth 2.0 JWT authentication 
+You can authenticate MQTT clients using JSON Web Tokens (JWT) issued by any third-party OpenID Connect (OIDC) identity provider. This authentication method provides a lightweight, secure, and flexible option for MQTT clients that aren't provisioned in Azure. For more information, see [Authenticate client using OAuth 2.0 JWT](mqtt-client-custom-jwt.md). 
+
+
 
 ## Related content
 - Learn how to [authenticate clients using certificate chain](mqtt-certificate-chain-client-authentication.md)
 - Learn how to [authenticate client using Microsoft Entra ID token](mqtt-client-azure-ad-token-and-rbac.md)
-- Learn how to [authenticate client using custom JWT](mqtt-client-custom-jwt.md)
+- Learn how to [authenticate client using OAuth 2.0 JWT](mqtt-client-custom-jwt.md) 
 - See [Transport layer security with MQTT broker](mqtt-transport-layer-security-flow.md)

articles/event-grid/media/authenticate-with-namespaces-using-json-web-tokens/direct-upload-option.png

@@ -1,31 +1,31 @@
 ---
-title: Custom JWT authentication
-description: Describes custom JWT authentication and authorization to publish or subscribe to MQTT messages
+title: OAuth 2.0 JWT authentication
+description: Describes OAuth 2.0 JWT authentication and authorization to publish or subscribe to MQTT messages
 ms.topic: conceptual
 ms.custom: build-2024
-ms.date: 01/27/2025
+ms.date: 04/30/2025
 author: Connected-Seth
 ms.author: seshanmugam
 ms.subservice: mqtt
 ---
 
-# Custom JWT authentication and authorization to publish or subscribe to MQTT messages
+# OAuth 2.0 JSON Web Token (JWT) authentication and authorization to publish or subscribe to MQTT messages 
 
-You can authenticate MQTT clients with Custom JWT to connect to the Event Grid namespace. You can embed and validate custom claims in the JWT to authorize publish or subscribe permissions to your Event Grid topic spaces.
+You can authenticate MQTT clients with OAuth 2.0 JWT to connect to the Event Grid namespace. You can embed and validate custom claims in the JWT to authorize publish or subscribe permissions to your Event Grid topic spaces.
 
 > [!IMPORTANT]
-> - This feature is supported only when using the MQTT v5 protocol version.
+> This feature is supported only when using the MQTT v5 protocol version.
 
 ## Prerequisites
-- You need an Event Grid namespace with MQTT enabled.  Learn about [creating Event Grid namespace](/azure/event-grid/create-view-manage-namespaces#create-a-namespace)
+- You need an Event Grid namespace with MQTT enabled. Learn about [creating Event Grid namespace](/azure/event-grid/create-view-manage-namespaces#create-a-namespace)
 
 <a name='authentication-using-azure-ad-jwt'></a>
 
-## Authentication using Custom JWT
-You can use the MQTT v5 CONNECT packet to provide the Custom JWT to authenticate your client and the MQTT v5 AUTH packet to refresh the token.  
+## Authentication using OAuth 2.0 JWT
+You can use the MQTT v5 CONNECT packet to provide the OAuth 2.0 JWT to authenticate your client and the MQTT v5 AUTH packet to refresh the token.  
 
 > [!IMPORTANT]
-> - If you don't set the CONNECT packet's authentication method to CUSTOM-JWT, you receive an 'invalid issuer' error—even if all other configurations are correct.
+> If you don't set the CONNECT packet's authentication method to CUSTOM-JWT, you receive an 'invalid issuer' error—even if all other configurations are correct.
 
 In the CONNECT packet, you can provide the required values in the following fields:
 
@@ -45,10 +45,10 @@ In the AUTH packet, you can provide the required values in the following fields:
 Authenticate Reason Code with value 25 signifies reauthentication.
 
 > [!NOTE]
-> - Audience: 'aud' claim must be set to "https://eventgrid.azure.net/".
+> Audience: `aud` claim must be set to `https://[namespace].ts.eventgrid.azure.net/`. 
 
 ## Access permissions
-A client using Custom JWT authentication can use client attributes and permissions to limit access to specific topics.
+A client using OAuth 2.0 JWT authentication can use client attributes and permissions to limit access to specific topics. 
 
 ## Next steps
 - See [Publish and subscribe to MQTT message using Event Grid](mqtt-publish-and-subscribe-portal.md)