Merge pull request #281951 from PatAltimore/patricka-expired-creds-release-aio-july-updates

Add MQTT broker client disconnect on expiration

Author: prmerger-automator[bot]

articles/iot-operations/create-edge-apps/howto-develop-mqttnet-apps.md

@@ -29,7 +29,7 @@ The [sample code](https://github.com/Azure-Samples/explore-iot-operations/tree/m
     var mqttClient = mqttFactory.CreateMqttClient();
     ```
 
-1. The following Kubernetes pod specification mounts the service account token to the specified path on the container file system. The mounted token is used as the password with well-known username `$sat`:
+1. The following Kubernetes pod specification mounts the service account token to the specified path on the container file system. The mounted token is used as the password with well-known username `K8S-SAT`:
 
     ```csharp
     string token_path = "/var/run/secrets/tokens/mqtt-client-token";
@@ -51,7 +51,7 @@ The [sample code](https://github.com/Azure-Samples/explore-iot-operations/tree/m
         .WithTcpServer(broker, 1883)
         .WithProtocolVersion(MqttProtocolVersion.V500)
         .WithClientId("sampleid")
-        .WithCredentials("$sat", satToken)
+        .WithCredentials("K8S-SAT", satToken)
         .Build();
     ```
 

articles/iot-operations/create-edge-apps/tutorial-event-driven-with-dapr.md

@@ -211,7 +211,7 @@ To verify the MQTT bridge is working, deploy an MQTT client to the cluster.
 1. Subscribe to the `sensor/window_data` topic to observe the published output from the Dapr application:
 
     ```bash
-    mosquitto_sub -L mqtts://aio-mq-dmqtt-frontend/sensor/window_data -u '$sat' -P $(cat /var/run/secrets/tokens/mqtt-client-token) --cafile /var/run/certs/aio-mq-ca-cert/ca.crt 
+    mosquitto_sub -L mqtts://aio-mq-dmqtt-frontend/sensor/window_data -u 'K8S-SAT' -P $(cat /var/run/secrets/tokens/mqtt-client-token) --cafile /var/run/certs/aio-mq-ca-cert/ca.crt 
     ```
 
 1. Verify the application is outputting a sliding windows calculation for the various sensors every 10 seconds:

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

@@ -7,7 +7,7 @@ ms.subservice: azure-mqtt-broker
 ms.topic: how-to
 ms.custom:
   - ignite-2023
-ms.date: 07/16/2024
+ms.date: 07/26/2024
 
 #CustomerIntent: As an operator, I want to configure authentication so that I have secure MQTT broker communications.
 ---
@@ -56,7 +56,7 @@ BrokerListener and BrokerAuthentication are separate resources, but they're link
 
 The order of authentication methods in the array determines how MQTT broker authenticates clients. MQTT broker tries to authenticate the client's credentials using the first specified method and iterates through the array until it finds a match or reaches the end.
 
-For each method, MQTT broker first checks if the client's credentials are *relevant* for that method. For example, SAT authentication requires a username starting with `$sat`, and X.509 authentication requires a client certificate. If the client's credentials are relevant, MQTT broker then verifies if they're valid. For more information, see the [Configure authentication method](#configure-authentication-method) section.
+For each method, MQTT broker first checks if the client's credentials are *relevant* for that method. For example, SAT authentication requires a username starting with `K8S-SAT`, and X.509 authentication requires a client certificate. If the client's credentials are relevant, MQTT broker then verifies if they're valid. For more information, see the [Configure authentication method](#configure-authentication-method) section.
 
 For custom authentication, MQTT broker treats failure to communicate with the custom authentication server as *credentials not relevant*. This behavior lets MQTT broker fall back to other methods if the custom server is unreachable.
 
@@ -92,7 +92,7 @@ The earlier example specifies custom and SAT. When a client connects, MQTT broke
 
 1. If the custom authentication server responds with `Pass` or `Fail` result, the authentication flow ends. However, if the custom authentication server isn't available, then MQTT broker falls back to the remaining specified methods, with SAT being next.
 
-1. MQTT broker tries to authenticate the credentials as SAT credentials. If the MQTT username starts with `$sat`, MQTT broker evaluates the MQTT password as a SAT.
+1. MQTT broker tries to authenticate the credentials as SAT credentials. If the MQTT username starts with `K8S-SAT`, MQTT broker evaluates the MQTT password as a SAT.
 
 If the custom authentication server is unavailable and all subsequent methods determined that the provided credentials aren't relevant, then the broker denies the client connection.
 
@@ -386,6 +386,25 @@ spec:
           header_key: header_value
 ```
 
+## Client disconnect after credentials expire
+
+MQTT broker disconnects clients when their credentials expire. Disconnect after credential expiration applies to all clients that connect to the MQTT broker frontends including:
+
+- Clients authenticated with SATs disconnect when their SAT expires
+- Clients authenticated with X.509 disconnect when their client certificate expires
+- Clients authenticated with custom authentication disconnect based on the expiry time returned from the custom authentication server.
+
+On disconnect, the client's network connection is closed. The client won't receive an MQTT DISCONNECT packet, but the broker logs a message that it disconnected the client.
+
+MQTT v5 clients authenticated with SATs and custom authentication can reauthenticate with a new credential before their initial credential expires. X.509 clients cannot reauthenticate and must re-establish the connection since authentication is done at the TLS layer.
+
+Clients can reauthenticate by sending an MQTT v5 AUTH packet.
+
+SAT clients send an AUTH client with the fields `method: K8S-SAT`, `data: <token>`.
+Custom authentication clients set the method and data field as required by the custom authentication server.
+
+Successful reauthentication updates the client's credential expiry with the expiry time of its new credential, and the broker responds with a *Success AUTH* packet. Failed authentication due to transient issues cause the broker to respond with a *ContinueAuthentication AUTH* packet. For example, the custom authentication server being unavailable. The client can try again later. Other authentication failures cause the broker to send a DISCONNECT packet and close the client's network connection.
+
 ## Related content
 
 - About [BrokerListener resource](howto-configure-brokerlistener.md)