AWS iot medium security documentation change
Summary
Significantly expanded MQTT connection management documentation including new sections on viewing connection details with GetConnection API, managing client subscriptions with ListSubscriptions API, and console-based connection management
Security assessment
The changes add documentation for the GetConnection API that exposes sensitive network information (source IP/port, target IP/port) which could be exploited if improperly accessed. It also details security controls like the iot:IncludeSocketInformation condition key for granular access control. The documentation explicitly warns about authentication requirements and potential misrouting vulnerabilities when client IDs contain special characters.
Diff
diff --git a/iot/latest/developerguide/mqtt.md b/iot/latest/developerguide/mqtt.md index 182855ece..42fc4f1f2 100644 --- a//iot/latest/developerguide/mqtt.md +++ b//iot/latest/developerguide/mqtt.md @@ -7 +7 @@ -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 +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 specificationsMQTT connection management @@ -17 +17 @@ 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. +After your clients are connected, you can monitor and manage their MQTT client connections using the console or APIs. For more information, see MQTT connection management. @@ -41 +41 @@ After your clients are connected, you can monitor and manage their MQTT client c - * Managing MQTT connections + * MQTT connection management @@ -180 +180 @@ 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. + * You manually disconnect the client and clear the session using the console or `DeleteConnection` API. For more information, see MQTT connection management. @@ -322 +322 @@ 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. 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. +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 MQTT connection management. @@ -384 +384 @@ 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. +When managing client connections, you can control whether LWT messages are published when you disconnect a client. For more information, see MQTT connection management. @@ -406 +406 @@ 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. +When managing client connectionsthrough the console or APIs, you can view the connection attributes and session configuration for connected clients. For more information, see MQTT connection management. @@ -498 +498 @@ 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). 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. +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 MQTT connection management. 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. @@ -676 +676 @@ 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. You can also manually disconnect clients using APIs. For more information, see Managing MQTT connections. + * 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 the console or APIs. For more information, see MQTT connection management. @@ -691 +691 @@ The message broker implementation is based on the [MQTT v3.1.1 specification](ht -## Managing MQTT connections +## MQTT connection management @@ -693 +693 @@ The message broker implementation is based on the [MQTT v3.1.1 specification](ht -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. +AWS IoT Core provides APIs and console features to help you manage MQTT connections, including the ability to disconnect clients, view connection details, and manage their sessions. These capabilities give you more control over your AWS IoT client fleet and help with troubleshooting connection issues. @@ -695 +695,14 @@ AWS IoT Core provides APIs to help you manage MQTT connections, including the ab -### DeleteConnection API +###### In this section + + * Disconnecting MQTT clients + + * Viewing connection details + + * Managing client subscriptions + + * CloudWatch Logs AWS IoT log entries + + + + +### Disconnecting MQTT clients @@ -735 +748 @@ 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. +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 is ignored. @@ -783 +796 @@ You can scope this permission to specific client IDs using resource-based polici - "Resource": "arn:aws:iot:region:account:client/myDevice*" + "Resource": "arn:aws:iot:us-east-1:987654321:client/myDevice*" @@ -832,0 +846,580 @@ The service is temporarily unavailable. Retry the request after a brief delay. +### Viewing connection details + +Use the `GetConnection` API to retrieve detailed information about active MQTT client connections, including connection status, session details, and network information. + +The `GetConnection` API returns comprehensive connection metadata that helps with troubleshooting connectivity issues, monitoring client behavior, and auditing connection patterns. You can use this information to understand client connection lifecycles and diagnose problems with MQTT sessions. Connection information is available for 30 minutes after disconnection regardless of whether the client used a clean or persistent session. For disconnected metatdata beyond 30 minutes, use the [GetThingConnectivityData](https://docs.aws.amazon.com/iot/latest/developerguide/device-connectivity-status.html) API which requires fleet indexing to be enabled. + +#### Use cases + +The `GetConnection` API is useful for troubleshooting connection issues and monitoring client behavior. You can verify client connectivity status, check persistent session settings, and review connection timestamps to understand client connectivity patterns. + +Network diagnostics also benefit from this API. The connection details include source and target IP addresses and ports, which help identify network routing issues or connection endpoint problems. This information is valuable when debugging connectivity problems or optimizing network configurations. + +#### API parameters + +The `GetConnection` API accepts the following parameters: + +clientId (required) + + +The unique identifier of the MQTT client to retrieve connection details for. 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 `GetConnection` 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. + +Routing considerations: URL encoding is required when client IDs contain both forward slashes and the string "subscriptions". Without proper encoding, the path structure may be misinterpreted and your request will be routed to the `ListSubscriptions` API instead of `GetConnection`. For instance, a client ID client/subscriptions must be encoded as client%2Fsubscriptions to ensure the request routes correctly to `GetConnection` rather than being interpreted as a `ListSubscriptions` call. + +includeSocketInformation (optional) + + +Type: Boolean + +Default: false + +The `includeSocketInformation` parameter controls whether socket-level network information is included in the API response. When set to `true`, the response includes the following fields: `sourceIp`, `sourcePort`, `targetIp`, `targetPort`, `vpcEndpointId`. When `includeSocketInformation` is not specified or set to `false`, these socket fields are excluded from the response. If the `includeSocketInformation` parameter is set to `true` but the caller lacks authorization to view socket information, the entire API call fails with 403 Forbidden. + +#### API syntax + +The `GetConnection` API uses the following HTTP request format: + + + GET /connections/<client-id>?includeSocketInformation=false HTTP/1.1 + +Example requests: + + + GET /connections/myDevice123?includeSocketInformation=false HTTP/1.1 + + // Get connection details for a client with special characters (URL encoded) + // Original client ID: "my device/123" + GET /connections/my%20device%2F123?includeSocketInformation=true HTTP/1.1 + +Example response for a connected client: + + + { + "clientId": "abcd12345fvgbh", + "connected": true, + "cleanSession": false, + "connectedSince": 1573002340451, + "thingName": "deviceABC", + "sourceIp": "203.0.113.1", + "sourcePort": 8883, + "targetIp": "198.51.100.1", + "targetPort": 8883, + "keepAliveDuration": 60, + "disconnectReason": null, + "sessionExpiry": 3600 + } + +Response fields: + +clientId + + +The client ID of the MQTT client. + +connected + + +The connection state of the client. Returns `true` if the client is currently connected to AWS IoT Core, or `false` if the client is not connected. + +cleanSession + + +Indicates whether the client is using a clean session. Returns `true` for clean sessions or `false` for persistent sessions. Clean sessions don't retain state after disconnection, while persistent sessions maintain subscriptions and queued messages. + +connectedSince + + +Unix timestamp (in milliseconds) indicating when the client connected. Present only when `connected` is `true`. + +disconnectedSince + + +Unix timestamp (in milliseconds) indicating when the client disconnected. Present only when `connected` is `false`. + +thingName + + +Thing name of the client, present only when there is a thing associated with the clientId. + +disconnectReason + + +The reason for the most recent disconnection, if the client is currently disconnected. This field helps identify whether the disconnection was client-initiated, server-initiated, or due to network issues. Present only when `connected` is `false`. For disconnect reason codes, see [LifeCycleEvents](./life-cycle-events.html). + +keepAliveDuration + + +The keep-alive interval in seconds that the client specified when establishing the connection. This determines how frequently the client sends keep-alive messages to maintain the connection. + +sourceIp + + +The IP address of the client that initiated the connection. Only returned if `includeSocketInformation` is set to `true` and you are authorized to retrieve this information. + +sourcePort + + +The port number used by the client for the connection. Only returned if `includeSocketInformation` is set to `true` and you are authorized to retrieve this information. + +targetIp + + +The IP address where the connection request was made to. Only returned if `includeSocketInformation` is set to `true` and you are authorized to retrieve this information. + +targetPort + + +The port number of the AWS IoT Core endpoint that the client connected to. Only returned if `includeSocketInformation` is set to `true` and you are authorized to retrieve this information. + +vpcEndpointId + + +The ID of the VPC endpoint. Present for clients connected to AWS IoT Core via a [VPC endpoint](./IoTCore-VPC.html). Only returned if `includeSocketInformation` is set to `true` and you are authorized to retrieve this information. + +sessionExpiry + +