AWS iot documentation change
Summary
Added comprehensive documentation for Managing MQTT connections including new DeleteConnection API details, session management, and client disconnection controls
Security assessment
The changes introduce documentation for connection management capabilities (DeleteConnection API) that enable administrators to forcibly disconnect clients and manage sessions. While this enhances security controls by allowing mitigation of unauthorized/misbehaving clients, there is no evidence it addresses a specific existing security vulnerability. The documentation adds security-adjacent features rather than patching a known issue.
Diff
diff --git a/iot/latest/developerguide/mqtt.md b/iot/latest/developerguide/mqtt.md index 525a8eb60..812d49c24 100644 --- a//iot/latest/developerguide/mqtt.md +++ b//iot/latest/developerguide/mqtt.md @@ -5 +5 @@ -Connecting with MQTT using the AWS IoT Device SDKsMQTT Quality of Service (QoS) optionsMQTT persistent sessionsMQTT retained messagesMQTT Last Will and Testament (LWT) messagesUsing connectAttributesMQTT 5 supported featuresMQTT 5 propertiesMQTT reason codesAWS IoT differences from MQTT specifications +Connecting with MQTT using the AWS IoT Device SDKsMQTT Quality of Service (QoS) optionsMQTT persistent sessionsMQTT retained messagesMQTT Last Will and Testament (LWT) messagesUsing connectAttributesMQTT 5 supported featuresMQTT 5 propertiesMQTT reason codesAWS IoT differences from MQTT specificationsManaging MQTT connections @@ -14,0 +15,2 @@ While we recommend using the AWS IoT Device SDKs to connect to AWS IoT, they are +After your clients are connected, you can monitor and manage their MQTT client connections using APIs. For more information, see Managing MQTT connections. + @@ -36,0 +39,2 @@ While we recommend using the AWS IoT Device SDKs to connect to AWS IoT, they are + * Managing MQTT connections + @@ -173,0 +178,2 @@ Persistent sessions can end in the following ways: + * You manually disconnect the client and clear the session using `DeleteConnection` API. For more information, see Managing MQTT connections. + @@ -314 +320 @@ The **Retained messages** page in the AWS IoT console provides a paginated list -The **MQTT test client** page in the AWS IoT console can subscribe and publish to MQTT topics. The publish option lets you set the `RETAIN` flag on the messages that you publish to simulate how your devices might behave. +The **MQTT test client** page in the AWS IoT console can subscribe and publish to MQTT topics. The publish option lets you set the RETAIN flag on the messages that you publish to simulate how your devices might behave. You can also use the MQTT test client to monitor messages from connected clients that you manage through the client connections interface. For more information about managing client connections, see Managing MQTT connections. @@ -375,0 +382,2 @@ Last Will and Testament (LWT) is a feature in MQTT. With LWT, clients can specif +When managing client connections, you can control whether LWT messages are published when you disconnect a client. For more information, see Managing MQTT connections. + @@ -395,0 +404,2 @@ By default, your policy has a non-persistent connection and there are no attribu +When managing client connections, you can view the connection attributes and session configuration for connected clients. For more information, see Managing MQTT connections. + @@ -486 +496 @@ Client 5 and client 6 share the subscription: `$share/consumer2/sports/tennis` -For more information about shared subscriptions limits, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html) from the _AWS General Reference_. To test shared subscriptions using the AWS IoT MQTT client in the [AWS IoT console](https://console.aws.amazon.com/iot/home), see [Testing Shared Subscriptions in the MQTT client](./view-mqtt-messages.html#view-mqtt-shared-subscriptions). For more information about shared subscriptions, see [Shared Subscriptions](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901250) from the MQTTv5.0 specification. +For more information about shared subscriptions limits, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html) from the _AWS General Reference_. To test shared subscriptions using the AWS IoT MQTT client in the [AWS IoT console](https://console.aws.amazon.com/iot/home), see [Testing Shared Subscriptions in the MQTT client](./view-mqtt-messages.html#view-mqtt-shared-subscriptions). You can also view which topics connected clients are subscribed to, including shared subscriptions, by using the client connection management features. For more information, see Managing MQTT connections. For more information about shared subscriptions, see [Shared Subscriptions](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901250) from the MQTTv5.0 specification. @@ -581 +591 @@ Subscription Identifier Available | A Boolean value that indicates whether AWS -MQTT 5 introduces improved error reporting with reason code responses. AWS IoT Core may return reason codes including but not limited to the following grouped by packets. For a complete list of reason codes supported by MQTT 5, see [MQTT 5 specifications](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901031). +MQTT 5 introduces improved error reporting with reason code responses. AWS IoT Core can return reason codes including but not limited to the following grouped by packets. For a complete list of reason codes supported by MQTT 5, see [MQTT 5 specifications](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901031). @@ -659 +669 @@ The message broker implementation is based on the [MQTT v3.1.1 specification](ht - * The message broker uses the client ID to identify each client. The client ID is passed in from the client to the message broker as part of the MQTT payload. Two clients with the same client ID can't be connected concurrently to the message broker. When a client connects to the message broker using a client ID that another client is using, the new client connection is accepted, and the previously connected client is disconnected. + * The message broker uses the client ID to identify each client. The client ID is passed in from the client to the message broker as part of the MQTT payload. Two clients with the same client ID can't be connected concurrently to the message broker. When a client connects to the message broker using a client ID that another client is using, the new client connection is accepted and the previously connected client is disconnected. You can also manually disconnect clients using APIs. For more information, see Managing MQTT connections. @@ -667 +677 @@ The message broker implementation is based on the [MQTT v3.1.1 specification](ht - * AWS IoT may have limits that are different from the specifications. For more information, see [AWS IoT Core message broker and protocol limits and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits) from the _AWS IoT Reference Guide_. + * AWS IoT can have limits that are different from the specifications. For more information, see [AWS IoT Core message broker and protocol limits and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits) from the _AWS IoT Reference Guide_. @@ -673,0 +684,142 @@ The message broker implementation is based on the [MQTT v3.1.1 specification](ht +## Managing MQTT connections + +AWS IoT Core provides APIs to help you manage MQTT connections, including the ability to disconnect clients and manage their sessions. These capabilities give you more control over your AWS IoT client fleet and help with troubleshooting connection issues. + +### DeleteConnection API + +Use the `DeleteConnection` API to disconnect MQTT devices from AWS IoT Core by specifying their client IDs. When you disconnect a client, AWS IoT Core disconnects the client from the AWS IoT Core message broker and can optionally clean the session state and suppress the Last Will and Testament (LWT) message. + +When you call the `DeleteConnection` API, AWS IoT Core performs several actions to ensure a clean disconnection. AWS IoT Core first sends an MQTT disconnect message to the client to terminate the MQTT session. The service then closes the underlying TCP/TLS socket. + +The message broker sends a `DISCONNECT` packet to the device and publishes a [lifecycle event](./life-cycle-events.html) with the disconnect reason `API_INITIATED_DISCONNECT`. This helps you identify when a disconnection was initiated through the API rather than by the client or due to network issues. You can monitor these events for visibility, troubleshooting, and auditing purposes. For example, you can use AWS IoT rules to process these events to track when and why clients were disconnected. + +If you set the `cleanSession` parameter to `true`, AWS IoT Core removes the client's session state, including all subscriptions and queued messages. If you clean a session, the persistent session is terminated. If the client was a persistent session and the `preventWillMessage` parameter is set to `false`, the service dispatches the LWT message if available, which is useful during planned maintenance operations. + +When you call the `DeleteConnection` API, the disconnection process begins immediately, but the exact timing of when the client recognizes the disconnection can vary based on network conditions and client implementation. Most clients will detect the disconnection within a few seconds, but in some cases with poor network connectivity, it might take longer for the client to recognize that it has been disconnected. + +###### Note + +By forcing a disconnect, a client has to re-authenticate and re-authorize with a fresh session state. The API call itself doesn't prevent reconnection of clients. If this is desired, then additionally a client's credential or policy must be modified before issuing the `DeleteConnection` API call. + +For information about pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). + +#### Use cases + +The `DeleteConnection` API is useful for managing misbehaving clients that exhibit problematic behavior or consume excessive resources. By forcing a disconnect, you can ensure that clients re-establish their connections with proper authentication and authorization, which can help resolve resource consumption problems. + +Client redirection scenarios also benefit from this API. When you need to redirect clients to different endpoints or AWS Regions, you can disconnect them programmatically and have them reconnect to a different AWS IoT Core endpoint by changing DNS settings. This API can help resolve stuck connections or clear problematic session states that might be preventing normal operation. + +#### API parameters + +The `DeleteConnection` API accepts the following parameters: + +clientId (required) + + +The unique identifier of the MQTT client to disconnect. This is specified in the URL path. The client ID can't start with a dollar sign ($). + +###### Note + +MQTT client IDs can contain characters that are not valid in HTTP requests. When using the `DeleteConnection` API, you must URL encode (percent-encode) any characters in the client ID that are valid in MQTT but not in HTTP. This includes special characters like spaces, forward slashes (/), and UTF-8 characters. For example, a space becomes %20, a forward slash becomes %2F, and the UTF-8 character ü becomes %C3%BC. Proper encoding ensures that MQTT client IDs are correctly transmitted in the HTTP-based API call. + +cleanSession (optional) + + +Specifies whether to remove the client's session state when disconnecting. Set to `true` to delete all session information, including subscriptions and queued messages. Set to `false` to preserve the session state. By default, this is set to `false` (preserves the session state). For clean sessions this parameter will be ignored. + +preventWillMessage (optional) + + +Controls whether AWS IoT Core dispatches the Last Will and Testament (LWT) message if available upon disconnection. Set to `true` to prevent dispatching the LWT message. Set to `false` to allow dispatching. By default, this is set to `false` (dispatches LWT if available). + +#### API syntax + +The `DeleteConnection` API uses the following HTTP request format: + + + DELETE /connections/<clientId>?cleanSession=<cleanSession>&preventWillMessage=<preventWillMessage> HTTP/1.1 + +Example requests: + + + // Basic disconnect (preserves session, allows LWT message) + DELETE /connections/myDevice123 HTTP/1.1 + + // Disconnect and clear session + DELETE /connections/myDevice123?cleanSession=TRUE HTTP/1.1 + + // Disconnect, clear session, and prevent LWT message + DELETE /connections/myDevice123?cleanSession=TRUE&preventWillMessage=TRUE HTTP/1.1 + +Successful requests return HTTP 200 OK with no response body. + +###### Note + +The service name used by [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) to sign requests is: _iotdevicegateway_. You can find your endpoint by using the `aws iot describe-endpoint --endpoint-type iot:Data-ATS` command. + +#### Required permissions + +To use the `DeleteConnection` API, you need the following IAM permission: + + + iot:DeleteConnection + +You can scope this permission to specific client IDs using resource-based policies. For example: + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "iot:DeleteConnection", + "Resource": "arn:aws:iot:region:account:client/myDevice*" + } + ] + } + +#### Important considerations + +Disconnected clients can immediately attempt to reconnect unless you have implemented additional logic to prevent reconnection. The disconnect operation only terminates the current connection and doesn't prevent a connection from reconnecting. If you need to prevent reconnection, consider implementing client-side logic or disabling the credential of a device. + +Rate limits apply to the API as part of standard AWS IoT Core API rate limiting. When planning bulk disconnection operations, ensure you account for these limits and implement appropriate retry logic and batching strategies to avoid throttling. For more information, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). + +#### Error responses + +The `DeleteConnection` API can return the following error responses: + +InvalidRequestException + + +The request is not valid. This can occur if the client ID format is invalid, contains a dollar sign ($) prefix, or if required parameters are missing. + +ResourceNotFoundException + + +The specified client ID does not exist or is not currently connected, and doesn't have a persistent session. + +UnauthorizedException + + +You are not authorized to perform this operation. Ensure you have the required `iot:DeleteConnection` permission. + +ForbiddenException + + +The caller isn't authorized to make the request. This might occur due to insufficient IAM permissions or resource-based policy restrictions. + +ThrottlingException + + +The rate exceeds the limit. Reduce the frequency of your API calls and implement appropriate retry logic with exponential backoff. + +InternalFailureException + + +An unexpected error has occurred. Retry the request after a brief delay. + +ServiceUnavailableException + + +The service is temporarily unavailable. Retry the request after a brief delay. + @@ -682 +834 @@ Device communication protocols -HTTPS +HTTPS publish