Merge pull request #293665 from Connected-Seth/azure-docs-pr

Documentation Updates for Custom JWT Authentication - Event Grid MQTT Broker

Author: JamesJBarnett

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

@@ -3,9 +3,9 @@ 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: 05/21/2024
-author: george-guirguis
-ms.author: geguirgu
+ms.date: 01/27/2025
+author: Connected-Seth
+ms.author: seshanmugam
 ---
 
 # Authenticate with namespaces using JSON Web Tokens
@@ -110,7 +110,25 @@ Use the following command to update your namespace with the custom JWT authentic
 
   
 ```azurecli-interactive
-az resource update --resource-type Microsoft.EventGrid/namespaces --api-version 2024-06-01-preview --ids /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dummy-cd-test/providers/Microsoft.EventGrid/namespaces/dummy-cd-test2 --set properties.topicSpacesConfiguration.clientAuthentication='{\"customJwtAuthentication\":{\"tokenIssuer\":\"dmpypin-issuer\",\"issuerCertificates\":[{\"certificateUrl\":\"https://dummyCert-cd-test.vault.azure.net/certificates/dummy-cd-test/4f844b284afd487e9bba0831191087br1\",\"identity\":{\"type\":\"SystemAssigned\"}}]}}' 
+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 format
 Json Web Tokens are divided into the JWT Header and JWT payload sections.
@@ -168,3 +186,4 @@ Event Grid maps all claims to client attributes if they have one of the followin
 
 ## Related content
 - [MQTT client authentication](mqtt-client-authentication.md)
+- [Authenticate client using custom JWT](mqtt-client-custom-jwt.md)

articles/event-grid/mqtt-client-authentication.md

@@ -2,9 +2,9 @@
 title: 'Azure Event Grid Namespace MQTT client authentication'
 description: 'Describes how MQTT clients are authenticated and mTLS connection is established when a client connects to Azure Event Grid’s MQTT broker feature.'
 ms.topic: concept-article
-ms.date: 01/21/2025
-author: george-guirguis
-ms.author: geguirgu
+ms.date: 01/27/2025
+author: Connected-Seth
+ms.author: seshanmugam
 ms.subservice: mqtt
 # Customer intent: I want to learn about different types of authentication that MQTT broker in Azure Event Grid supports. 
 ---
@@ -14,15 +14,20 @@ ms.subservice: mqtt
 Azure Event Grid's MQTT broker supports the following authentication modes. 
 
 - Certificate-based authentication
-- Microsoft Entra ID authentication 
+- Microsoft Entra ID authentication
+- Custom JWT 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)
+
 ## 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)
 - See [Transport layer security with MQTT broker](mqtt-transport-layer-security-flow.md)

articles/event-grid/mqtt-client-custom-jwt.md

@@ -0,0 +1,55 @@
+---
+title: Custom JWT authentication
+description: Describes custom JWT authentication and authorization to publish or subscribe to MQTT messages
+ms.topic: conceptual
+ms.custom: build-2024
+ms.date: 01/27/2025
+author: Connected-Seth
+ms.author: seshanmugam
+ms.subservice: mqtt
+---
+
+# Custom 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 token 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.
+
+## 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)
+
+<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 token 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.
+
+In the CONNECT packet, you can provide the required values in the following fields:
+
+|Field  | Value  |
+|---------|---------|
+|Authentication Method | CUSTOM-JWT |
+|Authentication Data | JWT token |
+
+In the AUTH packet, you can provide the required values in the following fields:
+
+|Field | Value |
+|---------|---------|
+| Authentication Method | CUSTOM-JWT |
+| Authentication Data | JWT token |
+| Authentication Reason Code | 25 |
+ 
+Authenticate Reason Code with value 25 signifies reauthentication.
+
+> [!NOTE]
+> - Audience: 'aud' claim must be set to "https://eventgrid.azure.net/".
+
+## Access permissions
+A client using Custom 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)
+- How to [Authenticate with namespaces using JSON Web Tokens](authenticate-with-namespaces-using-json-web-tokens.md)

articles/event-grid/mqtt-client-microsoft-entra-token-and-rbac.md

@@ -2,11 +2,10 @@
 title: Microsoft Entra `JWT` authentication and RBAC authorization for clients with Microsoft Entra identity
 description: Describes JWT authentication and RBAC roles to authorize clients with Microsoft Entra identity to publish or subscribe MQTT messages
 ms.topic: conceptual
-ms.custom:
-  - ignite-2023
-ms.date: 11/15/2023
-author: george-guirguis
-ms.author: geguirgu
+ms.custom: build-2024
+ms.date: 01/27/2025
+author: Connected-Seth
+ms.author: seshanmugam
 ms.subservice: mqtt
 ---
 
@@ -16,7 +15,6 @@ You can authenticate MQTT clients with Microsoft Entra JWT to connect to Event G
 
 > [!IMPORTANT]
 > - This feature is supported only when using MQTT v5 protocol version
-> - JWT authentication is supported for Managed Identities and Service principals only
 
 ## 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)

articles/event-grid/toc.yml

@@ -77,8 +77,10 @@ items:
             href: oauth-json-web-token-authentication.md
           - name: MQTT client authentication using certificates
             href: mqtt-client-certificate-authentication.md        
-          - name: JWT authentication and RBAC authorization for clients with Microsoft Entra identity
+          - name: Microsoft Entra JWT authentication and RBAC authorization for clients 
             href: mqtt-client-microsoft-entra-token-and-rbac.md
+          - name: OAuth 2.0 JSON Web Token authentication and authorization for clients 
+            href: mqtt-client-custom-jwt.md
           - name: Transport Layer Security connection with MQTT broker
             href: mqtt-transport-layer-security-flow.md
         - name: Reliability