edit pass: mqtt-broker-batch2

paulth1 · paulth1 · commit 04c1077e1991 · 2025-01-13T17:27:45.000-08:00
diff --git a/articles/iot-operations/manage-mqtt-broker/howto-configure-authorization.md b/articles/iot-operations/manage-mqtt-broker/howto-configure-authorization.md
@@ -21,7 +21,7 @@ Authorization policies determine what actions the clients can perform on the bro
 
 ## Link BrokerAuthorization to BrokerListener
 
-To link a *BrokerListener* to a *BrokerAuthorization* resource, specify the `authorizationRef` field in the `ports` setting of the *BrokerListener* resource. Similar to BrokerAuthentication, the *BrokerAuthorization* resource can be linked to multiple *BrokerListener* ports. The authorization policies apply to all linked listener ports. However, there's one key difference compared with BrokerAuthentication:
+To link a *BrokerListener* to a *BrokerAuthorization* resource, specify the `authorizationRef` field in the `ports` setting of the *BrokerListener* resource. Similar to BrokerAuthentication, the *BrokerAuthorization* resource can be linked to multiple *BrokerListener* ports. The authorization policies apply to all linked listener ports. There's one key difference compared with BrokerAuthentication:
 
 > [!IMPORTANT]
 > To have the *BrokerAuthorization* configuration apply to a listener port, at least one BrokerAuthentication must also be linked to that listener port.
@@ -30,18 +30,18 @@ To learn more about *BrokerListener*, see [BrokerListener resource](howto-config
 
 ## Authorization rules
 
-To configure authorization, create a *BrokerAuthorization* resource in your Kubernetes cluster. The following sections provide examples of how to configure authorization for clients that use usernames, attributes, X.509 certificates, and Kubernetes Service Account Tokens (SATs). For a list of the available settings, see the [Broker Authorization](/rest/api/iotoperations/broker-authorization) API reference.
+To configure authorization, create a *BrokerAuthorization* resource in your Kubernetes cluster. The following sections provide examples of how to configure authorization for clients that use usernames, attributes, X.509 certificates, and Kubernetes service account tokens (SATs). For a list of the available settings, see the [Broker Authorization](/rest/api/iotoperations/broker-authorization) API reference.
 
-The following example shows how to create a *BrokerAuthorization* resource using both usernames and attributes:
+The following example shows how to create a *BrokerAuthorization* resource by using both usernames and attributes.
 
 # [Portal](#tab/portal)
 
-1. In the Azure portal, navigate to your IoT Operations instance.
+1. In the Azure portal, go to your IoT Operations instance.
 1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authorization** tab.
 1. Choose an existing authentication policy or create a new one by selecting **Create authorization policy**.
 
-    :::image type="content" source="media/howto-configure-authorization/authorization-rules.png" alt-text="Screenshot using Azure portal to create broker authorization rules.":::
+    :::image type="content" source="media/howto-configure-authorization/authorization-rules.png" alt-text="Screenshot that shows using the Azure portal to create broker authorization rules.":::
 
 # [Bicep](#tab/bicep)
 
@@ -115,7 +115,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
 
 ```
 
-Deploy the Bicep file using Azure CLI.
+Deploy the Bicep file by using the Azure CLI:
 
 ```azurecli
 az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
@@ -155,30 +155,30 @@ To create this *BrokerAuthorization* resource, apply the YAML manifest to your K
 
 ---
 
-This broker authorization allows clients with client IDs `temperature-sensor` or `humidity-sensor`, or clients with attributes `organization` with value `contoso` and `city` with value `seattle`, to:
+This broker authorization allows clients with the client IDs `temperature-sensor` or `humidity-sensor`, or clients with the attributes `organization`, with the values `contoso` and `city`, and with the value `seattle`, to:
 
 - Connect to the broker.
 - Publish messages to telemetry topics scoped with their client IDs and organization. For example:
   - `temperature-sensor` can publish to `/telemetry/temperature-sensor` and `/telemetry/contoso`.
   - `humidity-sensor` can publish to `/telemetry/humidity-sensor` and `/telemetry/contoso`.
   - `some-other-username` can publish to `/telemetry/contoso`.
-- Subscribe to commands topics scoped with their organization. For example:
+- Subscribe to command topics scoped with their organization. For example:
   - `temperature-sensor` can subscribe to `/commands/contoso`.
   - `some-other-username` can subscribe to `/commands/contoso`.
 
-### Using username for authorization
+### Use a username for authorization
 
-To use the MQTT username for authorization, specify them as an array under `principals.usernames`. However, depending on the authentication method, the username might not be verified:
+To use the MQTT username for authorization, specify them as an array under `principals.usernames`. Depending on the authentication method, the username might not be verified:
 
-- **Kubernetes SAT** - Username shouldn't be used for authorization because it's not verified for MQTTv5 with enhanced authentication.
-- **X.509** - Username matches the CN from certificate and can be used for authorization rules.
-- **Custom** - Username should only be used for authorization rules if custom authentication validates the username.
+- **Kubernetes SAT**: Username shouldn't be used for authorization because it's not verified for MQTTv5 with enhanced authentication.
+- **X.509**: Username matches the common name (CN) from a certificate and can be used for authorization rules.
+- **Custom**: Username should only be used for authorization rules if custom authentication validates the username.
 
-To prevent security issues, only use the MQTT username for broker authorization when it can be verified.
+To prevent security issues, use the MQTT username for broker authorization only when it can be verified.
 
 ### Further limit access based on client ID
 
-Because the `principals` field is a logical OR, you can further restrict access based on client ID by adding the `clientIds` field to the `brokerResources` field. For example, to allow clients with client IDs that start with its building number to connect and publish telemetry to topics scoped with their building, use the following configuration:
+Because the `principals` field is a logical `OR`, you can further restrict access based on client IDs by adding the `clientIds` field to the `brokerResources` field. For example, to allow clients with client IDs that start with their building number to connect and publish telemetry to topics scoped with their building, use the following configuration:
 
 # [Portal](#tab/portal)
 
@@ -282,7 +282,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
 }
 ```
 
-Deploy the Bicep file using Azure CLI.
+Deploy the Bicep file by using the Azure CLI:
 
 ```azurecli
 az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
@@ -315,37 +315,37 @@ spec:
 
 ---
 
-Here, if the `clientIds` weren't set under the `Connect` method, a client with any client ID could connect as long as it had the `building` attribute set to `building22` or `building23`. By adding the `clientIds` field, only clients with client IDs that start with `building22` or `building23` can connect. This ensures not only that the client has the correct attribute but also that the client ID matches the expected pattern.
+Here, if the `clientIds` weren't set under the `Connect` method, a client with any client ID could connect as long as it had the `building` attribute set to `building22` or `building23`. When you add the `clientIds` field, only clients with client IDs that start with `building22` or `building23` can connect. This designation ensures that the client has the correct attribute and that the client ID matches the expected pattern.
 
 ## Authorize clients that use X.509 authentication
 
-Clients that use [X.509 certificates for authentication](./howto-configure-authentication.md) can be authorized to access resources based on X.509 properties present on their certificate or their issuing certificates up the chain.
+You can authorize clients that use [X.509 certificates for authentication](./howto-configure-authentication.md) to access resources based on X.509 properties present on their certificate or their issuing certificates up the chain.
 
-### Using attributes
+### Use attributes
 
 To create rules based on properties from a client's certificate, its root CA, or intermediate CA, define the X.509 attributes in the *BrokerAuthorization* resource. For more information, see [Certificate attributes](howto-configure-authentication.md#optional-certificate-attributes-for-authorization).
 
 ### With client certificate subject common name as username
 
-To create authorization policies based on the *client* certificate subject common name (CN) only, create rules based on the CN.
+To create authorization policies based on the *client* certificate subject CN only, create rules based on the CN.
 
-For example, if a client has a certificate with subject `CN = smart-lock`, its username is `smart-lock`. From there, create authorization policies as normal.
+For example, if a client has a certificate with the subject `CN = smart-lock`, its username is `smart-lock`. From there, create authorization policies as normal.
 
-## Authorize clients that use Kubernetes Service Account Tokens
+## Authorize clients that use Kubernetes service account tokens
 
-Authorization attributes for SATs are set as part of the [Service Account annotations](./howto-configure-authentication.md#kubernetes-service-account-tokens). For example, to add an authorization attribute named `group` with value `authz-sat`, run the command:
+Authorization attributes for SATs are set as part of the [service account annotations](./howto-configure-authentication.md#kubernetes-service-account-tokens). For example, to add an authorization attribute named `group` with the value `authz-sat`, run the command:
 
 ```bash
 kubectl annotate serviceaccount mqtt-client aio-broker-auth/group=authz-sat
 ```
 
 Attribute annotations must begin with `aio-broker-auth/` to distinguish them from other annotations.
 
-As the application has an authorization attribute called `authz-sat`, there's no need to provide a `clientId` or `username`. The corresponding *BrokerAuthorization* resource uses this attribute as a principal, for example:
+As the application has an authorization attribute called `authz-sat`, there's no need to provide a `clientId` or `username` value. The corresponding *BrokerAuthorization* resource uses this attribute as a principal, for example:
 
 # [Portal](#tab/portal)
 
-In the Broker authorization rules for your authorization policy, use the following configuration:
+In the broker authorization rules for your authorization policy, use the following configuration:
 
 ```json
 [
@@ -447,7 +447,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
 
 ```
 
-Deploy the Bicep file using Azure CLI.
+Deploy the Bicep file by using the Azure CLI:
 
 ```azurecli
 az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
@@ -493,8 +493,8 @@ To set up authorization for clients that use the state store, provide the follow
 
 ### State store keys
 
-The state store is accessed over the MQTT broker on topic `statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke`.
-Since clients have access to the topic, you can specify keys and access levels under the `stateStoreResources` section of the MQTT broker `brokerResources` configuration.
+The state store is accessed over MQTT broker on the topic `statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke`.
+Because clients have access to the topic, you can specify keys and access levels under the `stateStoreResources` section of the MQTT broker `brokerResources` configuration.
 
 The `stateStoreResources` section format consists of access level, a pattern indicator, and the pattern.
 
@@ -551,33 +551,39 @@ stateStoreResources:
 
 ---
 
-The `method` field specifies the access level.
-- Read access is specified with `read`, write access with `write`, and both with `readwrite`.
+The `method` field specifies the access level:
+
+- Read access is specified with `read`. Write access is specified with `write`. Read and write access is specified with `readwrite`.
 - Access level is required.
 - Read access level implies the actions of `get` and `keynotify`.
 - Write access level implies the actions of `set`, `del`, and `vdel`.
 
-The `keyType` field specifies the type of key matching.
-- `pattern` to use *glob* style pattern matching
-- `string`  to do exact match, for example when a key contains characters that might be otherwise matched as a pattern (`*`, `?`, `[0-9]`)
-- `binary`  to match a binary key
+The `keyType` field specifies the type of key matching:
+
+- `pattern`: Used for *Glob* style pattern matching.
+- `string`: Used to do exact match, for example, when a key contains characters that might be otherwise matched as a pattern (`*`, `?`, `[0-9]`).
+- `binary`: Used to match a binary key.
+
+The `keys` field specifies the keys to match. You can specify the keys as *Glob* style patterns, token substitutions, or exact strings.
 
-The `keys` field specifies the keys to match. The keys can be specified as *Glob* style patterns, token substitutions, or exact strings. 
 - *Glob* style examples:
+
     - `colors/*`: All keys under the "colors/" prefix
     - `number[0-9]`: Any key from "number0" to "number9"
-    - `char?`: Any key with prefix "char" and a single digit suffix, like "charA"
-    - `*`: Full access to all keys.
+    - `char?`: Any key with the prefix "char" and a single digit suffix, like "charA"
+    - `*`: Full access to all keys
+
 - State store keys also support token substitution when key type is `pattern` and curly braces are reserved for this purpose. Token substitution examples:
+
     - `clients/{principal.clientId}/*`
     - `usernames/{principal.username}/*`
     - `rooms/{principal.attributes.room}/*`
 
-Here's an example of how you might author your state store resources:
+Here's an example of how you might author your state store resources.
 
 # [Portal](#tab/portal)
 
-In the Broker authorization rules for your authorization policy, add a similar configuration:
+In the broker authorization rules for your authorization policy, add a similar configuration:
 
 ```json
 [
@@ -727,7 +733,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
 }
 ```
 
-Deploy the Bicep file using Azure CLI.
+Deploy the Bicep file by using the Azure CLI:
 
 ```azurecli
 az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
@@ -753,7 +759,7 @@ stateStoreResources:
 
 ## Update authorization
 
-Broker authorization resources can be updated at runtime without restart. All clients connected at the time of the update of policy are disconnected. Changing the policy type is also supported.
+You can update broker authorization resources at runtime without restart. All clients connected at the time of the update of policy are disconnected. Changing the policy type is also supported.
 
 ```bash
 kubectl edit brokerauthorization my-authz-policies
@@ -763,10 +769,10 @@ kubectl edit brokerauthorization my-authz-policies
 
 # [Portal](#tab/portal)
 
-1. In the Azure portal, navigate to your IoT Operations instance.
+1. In the Azure portal, go to your IoT Operations instance.
 1. Under **Components**, select **MQTT Broker**.
 1. Select the broker listener you want to edit from the list.
-1. On the port you want to disable authorization, select **None** in the authorization dropdown.
+1. On the port where you want to disable authorization, select **None** in the authorization dropdown.
 
 # [Bicep](#tab/bicep)
 
@@ -780,10 +786,10 @@ To disable authorization, omit `authorizationRef` in the `ports` setting of your
 
 ## Unauthorized publish in MQTT 3.1.1
 
-With MQTT 3.1.1, when a publish is denied, the client receives the PUBACK with no error because the protocol version doesn't support returning error code. MQTTv5 return PUBACK with reason code 135 (Not authorized) when publish is denied.
+With MQTT 3.1.1, when publish is denied, the client receives PUBACK with no error because the protocol version doesn't support returning error code. MQTTv5 returns PUBACK with reason code 135 (Not authorized) when publish is denied.
 
 ## Related content
 
-- About [BrokerListener resource](howto-configure-brokerlistener.md)
+- [BrokerListener resource](howto-configure-brokerlistener.md)
 - [Configure authentication for a BrokerListener](./howto-configure-authentication.md)
 - [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md)
