Merge pull request #290457 from PatAltimore/patricka-scrub-authorization-release-aio-ga

Add username clarification

Author: v-regandowner

articles/iot-operations/manage-mqtt-broker/howto-configure-authentication.md

@@ -240,6 +240,7 @@ resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authe
       {
         method: 'X509'
         x509Settings: {
+          trustedClientCaCert: 'client-ca'
           authorizationAttributes: {
             root: {
               attributes: {
@@ -303,8 +304,8 @@ spec:
         - my-audience
     - method: X509
       x509Settings:
+        trustedClientCaCert: client-ca
         authorizationAttributes:
-          trustedClientCaCert: client-ca
           root:
             attributes:
               organization: contoso

articles/iot-operations/manage-mqtt-broker/howto-configure-authorization.md

@@ -78,7 +78,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
       rules: [
         {
           principals: {
-            usernames: [
+            clientIds: [
               'temperature-sensor'
               'humidity-sensor'
             ]
@@ -96,7 +96,7 @@ resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authoriz
             {
               method: 'Publish'
               topics: [
-                '/telemetry/{principal.username}'
+                '/telemetry/{principal.clientId}'
                 '/telemetry/{principal.attributes.organization}'
               ]
             }
@@ -134,7 +134,7 @@ spec:
     cache: Enabled
     rules:
       - principals:
-          usernames:
+          clientIds:
             - "temperature-sensor"
             - "humidity-sensor"
           attributes:
@@ -144,7 +144,7 @@ spec:
           - method: Connect
           - method: Publish
             topics:
-              - "/telemetry/{principal.username}"
+              - "/telemetry/{principal.clientId}"
               - "/telemetry/{principal.attributes.organization}"
           - method: Subscribe
             topics:
@@ -155,17 +155,27 @@ To create this *BrokerAuthorization* resource, apply the YAML manifest to your K
 
 ---
 
-This broker authorization allows clients with usernames `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 client IDs `temperature-sensor` or `humidity-sensor`, or clients with attributes `organization` with value `contoso` and `city` with value `seattle`, to:
 
 - Connect to the broker.
-- Publish messages to telemetry topics scoped with their usernames and organization. For example:
+- 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:
   - `temperature-sensor` can subscribe to `/commands/contoso`.
   - `some-other-username` can subscribe to `/commands/contoso`.
 
+### Using 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:
+
+- **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.
+
+To prevent security issues, only use the MQTT username for broker authorization 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: