|
| 1 | +--- |
| 2 | +title: JWT authentication and RBAC authorization for clients with Azure AD identity |
| 3 | +description: Describes JWT authentication and RBAC roles to authorize clients with Azure AD identity to publish or subscribe MQTT messages |
| 4 | +ms.topic: conceptual |
| 5 | +ms.date: 8/11/2023 |
| 6 | +author: veyaddan |
| 7 | +ms.author: veyaddan |
| 8 | +--- |
| 9 | + |
| 10 | +# Authenticating and Authorizing access to publish or subscribe to MQTT messages |
| 11 | +You can authenticate MQTT clients with Azure AD JWT to connect to Event Grid namespace. You can use Azure role-based access control (Azure RBAC) to enable MQTT clients, with Azure Active Directory identity, to publish or subscribe access to specific topic spaces. |
| 12 | + |
| 13 | +> [!IMPORTANT] |
| 14 | +> This feature is supported only when using MQTT v5 |
| 15 | +
|
| 16 | +## Prerequisites |
| 17 | +- 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) |
| 18 | +- Review the process to [create a custom role](/azure/role-based-access-control/custom-roles-portal) |
| 19 | + |
| 20 | + |
| 21 | +## Authentication using Azure AD JWT |
| 22 | +You can use the MQTT v5 CONNECT packet to provide the Azure AD JWT token to authenticate your client, and you can use the MQTT v5 AUTH packet to refresh the token. |
| 23 | + |
| 24 | +In CONNECT packet, you can provide required values in the following fields: |
| 25 | + |
| 26 | +|Field | Value | |
| 27 | +|---------|---------| |
| 28 | +|Authentication Method | OAUTH2-JWT | |
| 29 | +|Authentication Data | JWT token | |
| 30 | + |
| 31 | +In AUTH packet, you can provide required values in the following fields: |
| 32 | + |
| 33 | +|Field | Value | |
| 34 | +|---------|---------| |
| 35 | +| Authentication Method | OAUTH2-JWT | |
| 36 | +| Authentication Data | JWT token | |
| 37 | +| Authentication Reason Code | 25 | |
| 38 | + |
| 39 | +Authenticate Reason Code with value 25 signifies reauthentication. |
| 40 | + |
| 41 | +> [!NOTE] |
| 42 | +> Audience: “aud” claim must be set to "https://eventgrid.azure.net/". |
| 43 | +
|
| 44 | +## Authorization to grant access permissions |
| 45 | +A client using Azure AD based JWT authentication needs to be authorized to communicate with the Event Grid namespace. You can create custom roles to enable the client to communicate with Event Grid instances in your resource group, and then assign the roles to the client. You can use following two data actions to provide publish or subscribe permissions, to clients with Azure AD identities, on specific topic spaces. |
| 46 | + |
| 47 | +**Topic spaces publish** data action |
| 48 | +Microsoft.EventGrid/topicSpaces/publish/action |
| 49 | + |
| 50 | +**Topic spaces subscribe** data action |
| 51 | +Microsoft.EventGrid/topicSpaces/subscribe/action |
| 52 | + |
| 53 | +> [!NOTE] |
| 54 | +> Currently, we recommend using custom roles with the actions provided. |
| 55 | +
|
| 56 | +### Custom roles |
| 57 | + |
| 58 | +You can create custom roles using the publish and subscribe actions. |
| 59 | + |
| 60 | +The following are sample role definitions that allow you to publish and subscribe to MQTT messages. These custom roles give permissions at topic space scope. You can also create roles to provide permissions at subscription, resource group scope. |
| 61 | + |
| 62 | +**EventGridMQTTPublisherRole.json**: MQTT messages publish operation. |
| 63 | + |
| 64 | +```json |
| 65 | +{ |
| 66 | + "roleName": "Event Grid namespace MQTT publisher", |
| 67 | + "description": "Event Grid namespace MQTT message publisher role", |
| 68 | + "assignableScopes": [ |
| 69 | + "/subscriptions/<subscription ID>/resourceGroups/<resource group name>/Microsoft.EventGrid/namespaces/<namespace name>/topicSpaces/<topicspace name>" |
| 70 | + ], |
| 71 | + "permissions": [ |
| 72 | + { |
| 73 | + "actions": [], |
| 74 | + "notActions": [], |
| 75 | + "dataActions": [ |
| 76 | + "Microsoft.EventGrid/topicSpaces/publish/action" |
| 77 | + ], |
| 78 | + "notDataActions": [] |
| 79 | + } |
| 80 | + ] |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +**EventGridMQTTSubscriberRole.json**: MQTT messages subscribe operation. |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + "roleName": "Event Grid namespace MQTT subscriber", |
| 89 | + "description": "Event Grid namespace MQTT message subscriber role", |
| 90 | + "assignableScopes": [ |
| 91 | + "/subscriptions/<subscription ID>/resourceGroups/<resource group name>/Microsoft.EventGrid/namespaces/<namespace name>/topicSpaces/<topicspace name>" |
| 92 | + ] |
| 93 | + "permissions": [ |
| 94 | + { |
| 95 | + "actions": [], |
| 96 | + "notActions": [], |
| 97 | + "dataActions": [ |
| 98 | + "Microsoft.EventGrid/topicSpaces/subscribe/action" |
| 99 | + ], |
| 100 | + "notDataActions": [] |
| 101 | + } |
| 102 | + ] |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +## Create custom roles |
| 107 | +1. Navigate to topic spaces page in your Event Grid namespace |
| 108 | +1. Select the topic space for which the custom RBAC role needs to be created |
| 109 | +1. Navigate to the Access control (IAM) page within the topic space |
| 110 | +1. In the Roles tab, right select any of the roles to clone a new custom role. Provide the custom role name. |
| 111 | +1. Switch the Baseline permissions to **Start from scratch** |
| 112 | +1. On the Permissions tab, select **Add permissions** |
| 113 | +1. In the selection page, find and select Microsoft Event Grid |
| 114 | + :::image type="content" source="./media/mqtt-client-azure-ad-token-and-rbac/event-grid-custom-role-permissions.png" lightbox="./media/mqtt-client-azure-ad-token-and-rbac/event-grid-custom-role-permissions.png" alt-text="Screenshot showing the Microsoft Event Grid option to find the permissions."::: |
| 115 | +1. Navigate to Data Actions |
| 116 | +1. Select **Topic spaces publish** data action and select **Add** |
| 117 | + :::image type="content" source="./media/mqtt-client-azure-ad-token-and-rbac/event-grid-custom-role-permissions-data-actions.png" lightbox="./media/mqtt-client-azure-ad-token-and-rbac/event-grid-custom-role-permissions-data-actions.png" alt-text="Screenshot showing the data action selection."::: |
| 118 | +1. Select Next to see the topic space in the Assignable scopes tab. You can add other assignable scopes if needed. |
| 119 | +1. Select **Create** in Review + create tab to create the custom role. |
| 120 | +1. Once the custom role is created, you can assign the role to an identity to provide the publish permission on the topic space. You can learn how to assign roles [here](/azure/role-based-access-control/role-assignments-portal). |
| 121 | + |
| 122 | +## Assign the custom role to your Azure AD identity |
| 123 | +1. In the Azure portal, navigate to your Event Grid namespace |
| 124 | +1. Navigate to the topic space to which you want to authorize access. |
| 125 | +1. Go to the Access control (IAM) page of the topic space |
| 126 | +1. Select the **Role assignments** tab to view the role assignments at this scope. |
| 127 | +1. Select **+ Add** and Add role assignment. |
| 128 | +1. On the Role tab, select the role that you created in the previous step. |
| 129 | +1. On the Members tab, select User, group, or service principal to assign the selected role to one or more service principals (applications). |
| 130 | + - Users and groups work when user/group belong to fewer than 200 groups. |
| 131 | +1. Select **Select members**. |
| 132 | +1. Find and select the users, groups, or service principals. |
| 133 | +1. Select **Review + assign** on the Review + assign tab. |
| 134 | + |
| 135 | +> [!NOTE] |
| 136 | +> You can follow similar steps to create and assign a custom Event Grid MQTT subscriber permission to a topic space. |
| 137 | +
|
| 138 | +## Next steps |
| 139 | +- See [Publish and subscribe to MQTT message using Event Grid](mqtt-publish-and-subscribe-portal.md) |
| 140 | +- To learn more about how Managed Identities work, you can refer to [How managed identities for Azure resources work with Azure virtual machines - Microsoft Entra](/azure/active-directory/managed-identities-azure-resources/how-managed-identities-work-vm) |
| 141 | +- To learn more about how to obtain tokens from Azure AD, you can refer to [obtaining Azure AD tokens](/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#get-a-token) |
| 142 | +- To learn more about Azure Identity client library, you can refer to [using Azure Identity client library](/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-the-azure-identity-client-library) |
| 143 | +- To learn more about implementing an interface for credentials that can provide a token, you can refer to [TokenCredential Interface](/java/api/com.azure.core.credential.tokencredential) |
| 144 | +- To learn more about how to authenticate using Azure Identity, you can refer to [examples](https://github.com/Azure/azure-sdk-for-java/wiki/Azure-Identity-Examples) |
0 commit comments