# Connect to AWS IoT Core AWS IoT Core supports connections with IoT devices, wireless gateways, services, and apps. Devices connect to AWS IoT Core so they can send data to and receive data from AWS IoT services and other devices. Apps and other services also connect to AWS IoT Core to control and manage the IoT devices and process the data from your IoT solution. This section describes how to choose the best way to connect and communicate with AWS IoT Core for each aspect of your IoT solution. ![\[Image showing how AWS IoT Core provides device endpoints to connect IoT devices to AWS IoT and service endpoints to connect apps and other services to AWS IoT Core.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/iot-endpoints.png) There are several ways to interact with AWS IoT. Apps and services can use the [AWS IoT Core - control plane endpoints](#iot-service-endpoint-intro) and devices can connect to AWS IoT Core by using the [AWS IoT device endpoints](#iot-device-endpoint-intro) or [AWS IoT Core for LoRaWAN Regions and endpoints](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-lorawan.html#connect-iot-lorawan-regions-endpoints). ## AWS IoT Core - control plane endpoints The **AWS IoT Core - control plane** endpoints provide access to functions that control and manage your AWS IoT solution. + **Endpoints** The **AWS IoT Core - control plane** and **AWS IoT Core Device Advisor control plane** endpoints are Region specific and are listed in [AWS IoT Core Endpoints and Quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html). The formats of the endpoints are as follows. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/connect-to-iot.html) + **IPv4 endpoints** — IPv4 endpoints support only IPv4 traffic, and are available for all Regions. IPv4 endpoints use the following naming convention: ``` iot.aws-region.amazonaws.com ``` For example the IPv4 endpoint name for the us-east-1 Region is `iot.us-east-1.amazonaws.com`. + **Dual-stack (IPv4 and IPv6) endpoints** — Dual-stack endpoints support both IPv4 and IPv6 traffic. When a request is made to a dual-stack endpoint, the endpoint URL resolves to an IPv6 or an IPv4 address, depending on the protocol used by the network and client. Dual-stack endpoints use the following naming convention: ``` iot.aws-region.api.aws ``` For example the dual-stack endpoint name for the us-east-1 Region is `iot.us-east-1.api.aws`. + **SDKs and tools** The [AWS SDKs](https://aws.amazon.com/tools/#SDKs) provide language-specific support for the AWS IoT Core APIs, and the APIs of other AWS services. The [AWS Mobile SDKs](https://aws.amazon.com/tools/#Mobile_SDKs) provide app developers with platform-specific support for the AWS IoT Core API, and other AWS services on mobile devices. The [AWS CLI](https://aws.amazon.com/cli/) provides command-line access to the functions provided by the AWS IoT service endpoints. [AWS Tools for PowerShell](https://aws.amazon.com/powershell/) provides tools to manage AWS services and resources in the PowerShell scripting environment. + **Authentication** The service endpoints use IAM users and AWS credentials to authenticate users. + **Learn more** For more information and links to SDK references, see [Connect to AWS IoT Core service endpoints](iot-connect-service.md). ## AWS IoT device endpoints The AWS IoT device endpoints support communication between your IoT devices and AWS IoT. + **Endpoints** The device endpoints support AWS IoT Core and AWS IoT Device Management functions. They are specific to your AWS account and you can see what they are by using the **[describe-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html)** command. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/connect-to-iot.html) If you are using dual-stack endpoints (IPv4 and IPv6) for data plane operations, use the `iot:Data-ATS` endpoint type. `iot:Jobs` can be used for IPv4 only. For more information about these endpoints and the functions that they support, see [AWS IoT device data and service endpoints](iot-connect-devices.md#iot-connect-device-endpoints). + **SDKs** The [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks) provide language-specific support for the Message Queueing Telemetry Transport (MQTT) and WebSocket Secure (WSS) protocols, which devices use to communicate with AWS IoT. [AWS Mobile SDKs](iot-connect-service.md#iot-connect-mobile-sdks) also provide support for MQTT device communications, AWS IoT APIs, and the APIs of other AWS services on mobile devices. + **Authentication** The device endpoints use X.509 certificates or AWS IAM users with credentials to authenticate users. + **Learn more** For more information and links to SDK references, see [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks). ## AWS IoT Core for LoRaWAN gateways and devices AWS IoT Core for LoRaWAN connects wireless gateways and devices to AWS IoT Core. + **Endpoints** AWS IoT Core for LoRaWAN manages the gateway connections to account and Region-specific AWS IoT Core endpoints. Gateways can connect to your account's Configuration and Update Server (CUPS) endpoint that AWS IoT Core for LoRaWAN provides. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/connect-to-iot.html) + **SDKs** The AWS IoT Wireless API that AWS IoT Core for LoRaWAN is built on is supported by the AWS SDK. For more information, see [AWS SDKs and Toolkits](https://aws.amazon.com/getting-started/tools-sdks/). + **Authentication** AWS IoT Core for LoRaWAN device communications use X.509 certificates to secure communications with AWS IoT. + **Learn more** For more information about configuring and connecting wireless devices, see [AWS IoT Core for LoRaWAN Regions and endpoints](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/lorawan-getting-started.html). # Connect to AWS IoT Core service endpoints You can access the features of the **AWS IoT Core - control plane** by using the AWS CLI, the AWS SDK for your preferred language, or by calling the REST API directly. We recommend using the AWS CLI or an AWS SDK to interact with AWS IoT Core because they incorporate the best practices for calling AWS services. Calling the REST APIs directly is an option, but you must provide [the necessary security credentials](https://docs.aws.amazon.com//general/latest/gr/signing_aws_api_requests.html) that enable access to the API. **Note** IoT devices should use [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks). The Device SDKs are optimized for use on devices, support MQTT communication with AWS IoT, and support the AWS IoT APIs most used by devices. For more information about the Device SDKs and the features they provide, see [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks). Mobile devices should use [AWS Mobile SDKs](#iot-connect-mobile-sdks). The Mobile SDKs provide support for AWS IoT APIs, MQTT device communications, and the APIs of other AWS services on mobile devices. For more information about the Mobile SDKs and the features they provide, see [AWS Mobile SDKs](#iot-connect-mobile-sdks). You can use AWS Amplify tools and resources in web and mobile applications to connect more easily to AWS IoT Core. For more information about connecting to AWS IoT Core by using Amplify, see [PubSub](https://docs.amplify.aws/react/build-a-backend/add-aws-services/pubsub/) in the Amplify documentation. The following sections describe the tools and SDKs that you can use to develop and interact with AWS IoT and other AWS services. For the complete list of AWS tools and development kits that are available to build and manage apps on AWS, see [Tools to Build on AWS](https://aws.amazon.com/tools/). ## AWS CLI for AWS IoT Core The AWS CLI provides command-line access to AWS APIs. + **Installation** For information about how to install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-install.html). + **Authentication** The AWS CLI uses credentials from your AWS account. + **Reference** For information about the AWS CLI commands for these AWS IoT Core services, see: + [AWS CLI Command Reference for IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html) + [AWS CLI Command Reference for IoT data](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html) + [AWS CLI Command Reference for IoT jobs data](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-jobs-data/index.html) + [AWS CLI Command Reference for IoT secure tunneling](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotsecuretunneling/index.html) For tools to manage AWS services and resources in the PowerShell scripting environment, see [AWS Tools for PowerShell](https://aws.amazon.com/powershell/). ## AWS SDKs With AWS SDKs, your apps and compatible devices can call AWS IoT APIs and the APIs of other AWS services. This section provides links to the AWS SDKs and to the API reference documentation for the APIs of the AWS IoT Core services. **The AWS SDKs support these AWS IoT Core APIs** + [AWS IoT](https://docs.aws.amazon.com//iot/latest/apireference/welcome.html) + [AWS IoT Data Plane](https://docs.aws.amazon.com//iot/latest/apireference/welcome.html) + [AWS IoT Jobs Data Plane](https://docs.aws.amazon.com//iot/latest/apireference/welcome.html) + [AWS IoT Secure Tunneling](https://docs.aws.amazon.com//iot/latest/apireference/welcome.html) + [AWS IoT Wireless](https://docs.aws.amazon.com/iot-wireless/latest/apireference/welcome.html) ------ #### [ C\$1\$1 ] **To install the [AWS SDK for C\$1\$1](https://aws.amazon.com/sdk-for-cpp/) and use it to connect to AWS IoT:** 1. Follow the instructions in [Getting Started Using the AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started.html) These instructions describe how to: + Install and build the SDK from source files + Provide credentials to use the SDK with your AWS account + Initialize and shutdown the SDK in your app or service + Create a CMake project to build your app or service 1. Create and run a sample app. For sample apps that use the AWS SDK for C\$1\$1, see [AWS SDK for C\$1\$1 Code Examples](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/programming-services.html). **Documentation for the AWS IoT Core services that the AWS SDK for C\$1\$1 supports** + [AWS::IoTClient" reference documentation](https://sdk.amazonaws.com/cpp/api/LATEST/root/html/index.html) + [Aws::IoTDataPlane::IoTDataPlaneClient reference documentation](http://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_io_t_data_plane_1_1_io_t_data_plane_client.html) + [Aws::IoTJobsDataPlane::IoTJobsDataPlaneClient reference documentation](http://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_io_t_jobs_data_plane_1_1_io_t_jobs_data_plane_client.html) + [Aws::IoTSecureTunneling::IoTSecureTunnelingClient reference documentation](http://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_io_t_secure_tunneling_1_1_io_t_secure_tunneling_client.html) ------ #### [ Go ] **To install the [AWS SDK for Go](https://aws.amazon.com/sdk-for-go/) and use it to connect to AWS IoT:** 1. Follow the instructions in [Getting Started with the AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html) These instructions describe how to: + Install the AWS SDK for Go + Get access keys for the SDK to access your AWS account + Import packages into the source code of our apps or services 1. Create and run a sample app. For sample apps that use the AWS SDK for Go, see [AWS SDK for Go Code Examples](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/common-examples.html). **Documentation for the AWS IoT Core services that the AWS SDK for Go supports** + [IoT reference documentation](https://docs.aws.amazon.com/sdk-for-go/api/service/iot/) + [IoTDataPlane reference documentation](https://docs.aws.amazon.com/sdk-for-go/api/service/iotdataplane/) + [IoTJobsDataPlane reference documentation](https://docs.aws.amazon.com/sdk-for-go/api/service/iotjobsdataplane/) + [IoTSecureTunneling reference documentation](https://docs.aws.amazon.com/sdk-for-go/api/service/iotsecuretunneling/) ------ #### [ Java ] **To install the [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/) and use it to connect to AWS IoT:** 1. Follow the instructions in [Getting Started with AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/getting-started.html) These instructions describe how to: + Sign up for AWS and Create an IAM User + Download the SDK + Set up AWS Credentials and Region + Use the SDK with Apache Maven + Use the SDK with Gradle 1. Create and run a sample app using one of the [AWS SDK for Java 2.x Code Examples](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/advanced-topics.html). 1. Review the [SDK API reference documentation](https://sdk.amazonaws.com/java/api/latest/) **Documentation for the AWS IoT Core services that the AWS SDK for Java supports** + [IotClient reference documentation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/iot/IotClient.html) + [IotDataPlaneClient reference documentation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/iotdataplane/IotDataPlaneClient.html) + [IotJobsDataPlaneClient reference documentation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/iotjobsdataplane/IotJobsDataPlaneClient.html) + [IoTSecureTunnelingClient reference documentation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/iotsecuretunneling/IoTSecureTunnelingClient.html) ------ #### [ JavaScript ] **To install the AWS SDK for JavaScript and use it to connect to AWS IoT:** 1. Follow the instructions in [Setting Up the AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-up.html). These instructions apply to using the AWS SDK for JavaScript in the browser and with Node.JS. Make sure you follow the directions that apply to your installation. These instructions describe how to: + Check for the prerequisites + Install the SDK for JavaScript + Load the SDK for JavaScript 1. Create and run a sample app to get started with the SDK as the getting started option for your environment describes. + Get started with the [AWS SDK for JavaScript in the Browser](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-started-browser.html), or + Get started with the [AWS SDK for JavaScript in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-started-nodejs.html) **Documentation for the AWS IoT Core services that the AWS SDK for JavaScript supports** + [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Iot.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Iot.html) + [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IotData.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IotData.html) + [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IoTJobsDataPlane.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IoTJobsDataPlane.html) + [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IoTSecureTunneling.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/IoTSecureTunneling.html) ------ #### [ .NET ] **To install the [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/) and use it to connect to AWS IoT:** 1. Follow the instructions in [Setting up your AWS SDK for .NET environment](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) 1. Follow the instructions in [Setting up your AWS SDK for .NET project](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) These instructions describe how to: + Start a new project + Obtain and configure AWS credentials + Install AWS SDK packages 1. Create and run one of the sample programs in [Working with AWS services in the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/tutorials-examples.html) 1. Review the [SDK API reference documentation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html) **Documentation for the AWS IoT Core services that the AWS SDK for .NET supports** + [Amazon.IoT.Model reference documentation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IoT/NIoTModel.html) + [Amazon.IotData.Model reference documentation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IotData/NIotDataModel.html) + [Amazon.IoTJobsDataPlane.Model reference documentation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IoTJobsDataPlane/NIoTJobsDataPlaneModel.html) + [Amazon.IoTSecureTunneling.Model reference documentation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IoTSecureTunneling/NIoTSecureTunnelingModel.html) ------ #### [ PHP ] **To install the [AWS SDK for PHP](https://aws.amazon.com/sdk-for-php/) and use it to connect to AWS IoT:** 1. Follow the instructions in [Getting Started with the AWS SDK for PHP Version 3](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/getting-started_index.html) These instructions describe how to: + Check for the prerequisites + Install the SDK + Apply the SDK to a PHP script 1. Create and run a sample app using one of the [AWS SDK for PHP Version 3 Code Examples](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/examples_index.html) **Documentation for the AWS IoT Core services that the AWS SDK for PHP supports** + [IoTClient reference documentation](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.Iot.IotClient.html) + [IoTDataPlaneClient reference documentation](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.IotDataPlane.IotDataPlaneClient.html) + [IoTJobsDataPlaneClient reference documentation](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.IoTJobsDataPlane.IoTJobsDataPlaneClient.html) + [IoTSecureTunnelingClient reference documentation](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.IoTSecureTunneling.IoTSecureTunnelingClient.html) ------ #### [ Python ] **To install the [AWS SDK for Python (Boto3)](https://aws.amazon.com/sdk-for-python/) and use it to connect to AWS IoT:** 1. Follow the instructions in the [AWS SDK for Python (Boto3) Quickstart](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) These instructions describe how to: + Install the SDK + Configure the SDK + Use the SDK in your code 1. Create and run a sample program that uses the AWS SDK for Python (Boto3) This program displays the account's currently configured logging options. After you install the SDK and configure it for your account, you should be able to run this program. ``` import boto3 import json # initialize client iot = boto3.client('iot') # get current logging levels, format them as JSON, and write them to stdout response = iot.get_v2_logging_options() print(json.dumps(response, indent=4)) ``` For more information about the function used in this example, see [Configure AWS IoT logging](configure-logging.md). **Documentation for the AWS IoT Core services that the AWS SDK for Python (Boto3) supports** + [IoT reference documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iot.html) + [IoTDataPlane reference documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iot-data.html) + [IoTJobsDataPlane reference documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iot-jobs-data.html) + [IoTSecureTunneling reference documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/iotsecuretunneling.html) ------ #### [ Ruby ] **To install the [AWS SDK for Ruby](https://aws.amazon.com/sdk-for-ruby/) and use it to connect to AWS IoT:** + Follow the instructions in [Getting Started with the AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/getting-started.html) These instructions describe how to: + Install the SDK + Configure the SDK + Create and run the [Hello World Tutorial](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/hello.html) **Documentation for the AWS IoT Core services that the AWS SDK for Ruby supports** + [Aws::IoT::Client reference documentation](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/IoT/Client.html) + [Aws::IoTDataPlane::Client reference documentation](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/IoTDataPlane/Client.html) + [Aws::IoTJobsDataPlane::Client reference documentation](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/IoTJobsDataPlane/Client.html) + [Aws::IoTSecureTunneling::Client reference documentation](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/IoTSecureTunneling/Client.html) ------ ## AWS Mobile SDKs The AWS Mobile SDKs provide mobile app developers platform-specific support for the APIs of the AWS IoT Core services, IoT device communication using MQTT, and the APIs of other AWS services. ------ #### [ Android ] **AWS Mobile SDK for Android** The AWS Mobile SDK for Android contains a library, samples, and documentation for developers to build connected mobile applications using AWS. This SDK also includes support for MQTT device communications and calling the APIs of the AWS IoT Core services. For more information, see the following: + [AWS Mobile SDK for Android on GitHub](https://github.com/aws/aws-sdk-android) + [AWS Mobile SDK for Android Readme](https://github.com/aws-amplify/aws-sdk-android/blob/main/README.md#aws-sdk-for-android) + [AWS Mobile SDK for Android Samples](https://github.com/awslabs/aws-sdk-android-samples#aws-sdk-for-android-samples) + [AWS SDK for Android API reference](https://aws-amplify.github.io/aws-sdk-android/docs/reference/) + [AWSIoTClient Class reference documentation](https://aws-amplify.github.io/aws-sdk-android/docs/reference/com/amazonaws/services/iot/AWSIotClient.html) ------ #### [ iOS ] **AWS Mobile SDK for iOS** The AWS Mobile SDK for iOS is an open-source software development kit, distributed under an Apache Open Source license. The SDK for iOS provides a library, code samples, and documentation to help developers build connected mobile applications using AWS. This SDK also includes support for MQTT device communications and calling the APIs of the AWS IoT Core services. For more information, see the following: + [AWS Mobile SDK for iOS on GitHub](https://github.com/aws/aws-sdk-ios) + [AWS SDK for iOS Readme](https://github.com/aws-amplify/aws-sdk-ios/blob/main/README.md#aws-sdk-for-ios) + [AWS SDK for iOS Samples](https://github.com/awslabs/aws-sdk-ios-samples#the-aws-sdk-for-ios-samples) + [AWS IoT Class reference docs in the AWS SDK for iOS](https://aws-amplify.github.io/aws-sdk-ios/docs/reference/AWSIoT/index.html) ------ ## REST APIs of the AWS IoT Core services The REST APIs of the AWS IoT Core services can be called directly by using HTTP requests. + **Endpoint URL** The service endpoints that expose the REST APIs of the AWS IoT Core services vary by Region and are listed in [AWS IoT Core Endpoints and Quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html). You must use the endpoint for the Region that has the AWS IoT resources that you want to access, because AWS IoT resources are Region specific. + **Authentication** The REST APIs of the AWS IoT Core services use AWS IAM credentials for authentication. For more information, see [Signing AWS API requests](https://docs.aws.amazon.com//general/latest/gr/signing_aws_api_requests.html) in the AWS General Reference. + **API reference** For information about the specific functions provided by the REST APIs of the AWS IoT Core services, see: + [API reference for IoT](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT.html). + [API reference for IoT data](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT_Data_Plane.html). + [API reference for IoT jobs data](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT_Jobs_Data_Plane.html). + [API reference for IoT secure tunneling](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT_Secure_Tunneling.html). # Connect devices to AWS IoT Devices connect to AWS IoT and other services through AWS IoT Core. Through AWS IoT Core, devices send and receive messages using device endpoints that are specific to your account. The [AWS IoT Device SDKs](#iot-connect-device-sdks) support device communications using the MQTT and WSS protocols. For more information about the protocols that devices can use, see [Device communication protocols](protocols.md). **The message broker** AWS IoT manages device communication through a message broker. Devices and clients publish messages to the message broker and also subscribe to messages that the message broker publishes. Messages are identified by an application-defined [*topic*](topics.md). When the message broker receives a message published by a device or client, it republishes that message to the devices and clients that have subscribed to the message's topic. The message broker also forwards messages to the AWS IoT [rules](iot-rules.md) engine, which can act on the content of the message. **AWS IoT message security** Device connections to AWS IoT use [X.509 client certificates](x509-client-certs.md) and [AWS signature V4](https://docs.aws.amazon.com//general/latest/gr/signing_aws_api_requests.html) for authentication. Device communications are secured by TLS version 1.3 and AWS IoT requires devices to send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1) when they connect. For more information, see [Transport Security in AWS IoT](transport-security.html). ## AWS IoT device data and service endpoints **Important** You can cache or store the endpoints in your device. This means you won't need to query the `DescribeEndpoint` API every time when a new device is connected. The endpoints won't change after AWS IoT Core creates them for your account. Each account has several device endpoints that are unique to the account and support specific IoT functions. The AWS IoT device data endpoints support a publish/subscribe protocol that is designed for the communication needs of IoT devices; however, other clients, such as apps and services, can also use this interface if their application requires the specialized features that these endpoints provide. The AWS IoT device service endpoints support device-centric access to security and management services. To learn your account's device data endpoint, you can find it in the [https://console.aws.amazon.com//iot/home#/settings](https://console.aws.amazon.com//iot/home#/settings) page of your AWS IoT Core console. To learn your account's device endpoint for a specific purpose, including the device data endpoint, use the **describe-endpoint** CLI command shown here, or the `DescribeEndpoint` REST API, and provide the `endpointType` parameter value from the following table. ``` aws iot describe-endpoint --endpoint-type endpointType ``` This command returns an *iot-endpoint* in the following format: `account-specific-prefix.iot.aws-region.amazonaws.com`. Every customer has an `iot:Data-ATS` and an `iot:Data` endpoint. Each endpoint uses an X.509 certificate to authenticate the client. We strongly recommend that customers use the newer `iot:Data-ATS` endpoint type to avoid issues related to the widespread distrust of Symantec certificate authorities. We provide the `iot:Data` endpoint for devices to retrieve data from old endpoints that use VeriSign certificates for backward compatibility. For more information, see [Server Authentication](server-authentication.html). **AWS IoT endpoints for devices** | Endpoint purpose | `endpointType` value | Description | | --- | --- | --- | | AWS IoT Core - data plane operations | `iot:Data-ATS` | Used to send and receive data to and from the message broker, [Device Shadow](iot-device-shadows.md), and [Rules Engine](iot-rules.md) components of AWS IoT. `iot:Data-ATS` returns an ATS signed data endpoint. | | AWS IoT Core - data plane operations (legacy) | `iot:Data` | iot:Data returns a VeriSign signed data endpoint provided for backward compatibility. MQTT 5 is not supported on Symantec (iot:Data) endpoints. | | AWS IoT Core credential access | `iot:CredentialProvider` | Used to exchange a device's built-in X.509 certificate for temporary credentials to connect directly with other AWS services. For more information about connecting to other AWS services, see [Authorizing Direct Calls to AWS Services](authorizing-direct-aws.md). | | AWS IoT Device Management - jobs data operations | `iot:Jobs` | Used to enable devices to interact with the AWS IoT Jobs service using the [Jobs Device HTTPS APIs](jobs-mqtt-api.md). `iot:Jobs` can be used for IPv4 only. If you are using dual-stack endpoints (IPv4 and IPv6), use the `iot:Data-ATS` endpoint type. | | AWS IoT Device Advisor operations | `iot:DeviceAdvisor` | A test endpoint type used for testing devices with Device Advisor. For more information, see [Device Advisor](device-advisor.md). | | AWS IoT Core data beta (preview) | `iot:Data-Beta` | An endpoint type reserved for beta releases. For information about its current use, see [Domain configurations](iot-custom-endpoints-configurable.md). | You can also use your own fully-qualified domain name (FQDN), such as *example.com*, and the associated server certificate to connect devices to AWS IoT by using [Domain configurations](iot-custom-endpoints-configurable.md). ## AWS IoT Device SDKs The AWS IoT Device SDKs help you connect your IoT devices to AWS IoT Core and they support MQTT and MQTT over WSS protocols. The AWS IoT Device SDKs differ from the AWS SDKs in that the AWS IoT Device SDKs support the specialized communications needs of IoT devices, but don't support all of the services supported by the AWS SDKs. The AWS IoT Device SDKs are compatible with the AWS SDKs that support all of the AWS services; however, they use different authentication methods and connect to different endpoints, which could make using the AWS SDKs impractical on an IoT device. **Mobile devices** The [AWS Mobile SDKs](iot-connect-service.md#iot-connect-mobile-sdks) support both MQTT device communications, some of the AWS IoT service APIs, and the APIs of other AWS services. If you're developing on a supported mobile device, review its SDK to see if it's the best option for developing your IoT solution. ------ #### [ C\$1\$1 ] **AWS IoT C\$1\$1 Device SDK** The AWS IoT C\$1\$1 Device SDK allows developers to build connected applications using AWS and the APIs of the AWS IoT Core services. Specifically, this SDK was designed for devices that are not resource constrained and require advanced features such as message queuing, multi-threading support, and the latest language features. For more information, see the following: + [AWS IoT Device SDK C\$1\$1 v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-cpp-v2) + [AWS IoT Device SDK C\$1\$1 v2 Readme](https://github.com/aws/aws-iot-device-sdk-cpp-v2#aws-iot-device-sdk-for-c-v2) + [AWS IoT Device SDK C\$1\$1 v2 Samples](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples#sample-apps-for-the-aws-iot-device-sdk-for-c-v2) + [AWS IoT Device SDK C\$1\$1 v2 API documentation](https://aws.github.io/aws-iot-device-sdk-cpp-v2/) ------ #### [ Python ] **AWS IoT Device SDK for Python** The AWS IoT Device SDK for Python makes it possible for developers to write Python scripts to use their devices to access the AWS IoT platform through MQTT or MQTT over the WebSocket Secure (WSS) protocol. By connecting their devices to the APIs of the AWS IoT Core services, users can securely work with the message broker, rules, and Device Shadow service that AWS IoT Core provides and with other AWS services like AWS Lambda, Amazon Kinesis, and Amazon S3, and more. + [AWS IoT Device SDK for Python v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-python-v2) + [AWS IoT Device SDK for Python v2 Readme](https://github.com/aws/aws-iot-device-sdk-python-v2#aws-iot-device-sdk-v2-for-python) + [AWS IoT Device SDK for Python v2 Samples](https://github.com/aws/aws-iot-device-sdk-python-v2/tree/main/samples#sample-apps-for-the-aws-iot-device-sdk-v2-for-python) + [AWS IoT Device SDK for Python v2 API documentation](https://aws.github.io/aws-iot-device-sdk-python-v2/) ------ #### [ JavaScript ] **AWS IoT Device SDK for JavaScript** The AWS IoT Device SDK for JavaScript makes it possible for developers to write JavaScript applications that access APIs of the AWS IoT Core using MQTT or MQTT over the WebSocket protocol. It can be used in Node.js environments and browser applications. For more information, see the following: + [AWS IoT Device SDK for JavaScript v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-js-v2) + [AWS IoT Device SDK for JavaScript v2 Readme](https://github.com/aws/aws-iot-device-sdk-js-v2#aws-iot-device-sdk-for-javascript-v2) + [AWS IoT Device SDK for JavaScript v2 Samples](https://github.com/aws/aws-iot-device-sdk-js-v2/tree/main/samples#sample-apps-for-the-aws-iot-device-sdk-for-javascript-v2) + [AWS IoT Device SDK for JavaScript v2 API documentation](https://aws.github.io/aws-iot-device-sdk-js-v2/index.html) ------ #### [ Java ] **AWS IoT Device SDK for Java** The AWS IoT Device SDK for Java makes it possible for Java developers to access the APIs of the AWS IoT Core through MQTT or MQTT over the WebSocket protocol. The SDK supports the Device Shadow service. You can access shadows by using HTTP methods, including GET, UPDATE, and DELETE. The SDK also supports a simplified shadow access model, which allows developers to exchange data with shadows by using getter and setter methods, without having to serialize or deserialize any JSON documents. For more information, see the following: + [AWS IoT Device SDK for Java v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-java-v2) + [AWS IoT Device SDK for Java v2 Readme](https://github.com/aws/aws-iot-device-sdk-java-v2#aws-iot-device-sdk-for-java-v2) + [AWS IoT Device SDK for Java v2 Samples](https://github.com/aws/aws-iot-device-sdk-java-v2/tree/main/samples#sample-apps-for-the-aws-iot-device-sdk-for-java-v2) + [AWS IoT Device SDK for Java v2 API documentation](https://aws.github.io/aws-iot-device-sdk-java-v2/) ------ #### [ Embedded C ] **AWS IoT Device SDK for Embedded C** **Important** This SDK is intended for use by experienced embedded-software developers. The AWS IoT Device SDK for Embedded C (C-SDK) is a collection of C source files under the MIT open source license that can be used in embedded applications to securely connect IoT devices to AWS IoT Core. It includes MQTT, JSON Parser, and AWS IoT Device Shadow libraries and others. It is distributed in source form and intended to be built into customer firmware along with application code, other libraries and, optionally, an RTOS (Real Time Operating System). The AWS IoT Device SDK for Embedded C is generally targeted at resource constrained devices that require an optimized C language runtime. You can use the SDK on any operating system and host it on any processor type (for example, MCUs and MPUs). If your device has sufficient memory and processing resources available, we recommend that you use one of the other AWS IoT Device and Mobile SDKs, such as the AWS IoT Device SDK for C\$1\$1, Java, JavaScript, or Python. For more information, see the following: + [AWS IoT Device SDK for Embedded C on GitHub](https://github.com/aws/aws-iot-device-sdk-embedded-C) + [AWS IoT Device SDK for Embedded C Readme](https://github.com/aws/aws-iot-device-sdk-embedded-C#aws-iot-device-sdk-for-embedded-c) + [AWS IoT Device SDK for Embedded C Samples](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/docs/doxygen/output/html/demos_main.html) ------ # Device communication protocols AWS IoT Core supports devices and clients that use the MQTT and the MQTT over WebSocket Secure (WSS) protocols to publish and subscribe to messages, and devices and clients that use the HTTPS protocol to publish messages. All protocols support IPv4 and IPv6. This section describes the different connection options for devices and clients. ## TLS protocol versions AWS IoT Core uses [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) [version 1.2](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2) and [TLS version 1.3](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.3) to encrypt all communication. You can configure additional TLS policy versions for your endpoint by [configuring TLS settings in domain configurations](https://docs.aws.amazon.com//iot/latest/developerguide/iot-endpoints-tls-config.html). When connecting devices to AWS IoT Core, clients can send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1), which is required for features such as [multi-account registration](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html#multiple-account-cert), [configurable endpoints](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable.html), [custom domains](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable-custom.html), and [VPC endpoints](https://docs.aws.amazon.com//iot/latest/developerguide/IoTCore-VPC.html). For more information, see [Transport Security in AWS IoT](transport-security.html). The [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks) support MQTT and MQTT over WSS and support the security requirements of client connections. We recommend using the [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks) to connect clients to AWS IoT. ## Protocols, port mappings, and authentication How a device or client connects to the message broker is configurable using an [authentication type](#connection-protocol-auth-mode). By default or when no SNI extension is sent, authentication method is based on application protocol, port, and Application Layer Protocol Negotiation (ALPN) TLS extension that devices use. The following table lists the authentication expected based on port, port, and ALPN. **Protocols, authentication, and port mappings** | Protocol | Operations supported | Authentication | Port | ALPN protocol name | | --- | --- | --- | --- | --- | | MQTT over WebSocket | Publish, Subscribe | Signature Version 4 | 443 | N/A | | MQTT over WebSocket | Publish, Subscribe | Custom authentication | 443 | N/A | | MQTT | Publish, Subscribe | X.509 client certificate | 443† | `x-amzn-mqtt-ca` | | MQTT | Publish, Subscribe | X.509 client certificate | 8883 | N/A | | MQTT | Publish, Subscribe | Custom authentication | 443† | `mqtt` | | HTTPS | Publish only | Signature Version 4 | 443 | N/A | | HTTPS | Publish only | X.509 client certificate | 443† | `x-amzn-http-ca` | | HTTPS | Publish only | X.509 client certificate | 8443 | N/A | | HTTPS | Publish only | Custom authentication | 443 | N/A | **Application Layer Protocol Negotiation (ALPN)** †When using default endpoint configurations, clients that connect on port 443 with X.509 client certificate authentication must implement the [Application Layer Protocol Negotiation (ALPN)](https://tools.ietf.org/html/rfc7301) TLS extension and use the [ALPN protocol name](https://tools.ietf.org/html/rfc7301#section-3.1) listed in the ALPN ProtocolNameList sent by the client as part of the `ClientHello` message. On port 443, the [IoT:Data-ATS](iot-connect-devices.md#iot-connect-device-endpoint-table) endpoint supports ALPN x-amzn-http-ca HTTP, but the [IoT:Jobs](iot-connect-devices.md#iot-connect-device-endpoint-table) endpoint does not. On port 8443 HTTPS and port 443 MQTT with ALPN x-amzn-mqtt-ca, [custom authentication](custom-authentication.md) can't be used. Clients connect to their AWS account's device endpoints. See [AWS IoT device data and service endpoints](iot-connect-devices.md#iot-connect-device-endpoints) for information about how to find your account's device endpoints. **Note** AWS SDKs don't require the entire URL. They only require the endpoint hostname such as the [`pubsub.py` sample for AWS IoT Device SDK for Python on GitHub](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/master/samples/pubsub.py#L100). Passing the entire URL as provided in the following table can generate an error such as invalid hostname. **Connecting to AWS IoT Core** | Protocol | Endpoint or URL | | --- | --- | | MQTT | `iot-endpoint` | | MQTT over WSS | `wss://iot-endpoint/mqtt` | | HTTPS | `https://iot-endpoint/topics` | ## Choosing an application protocol for your device communication For most IoT device communication through the device endpoints, you'll want to use the Secure MQTT or MQTT over WebSocket Secure (WSS) protocols; however, the device endpoints also support HTTPS. The following table compares how AWS IoT Core uses the two high-level protocols (MQTT and HTTPS) for device communication. **AWS IoT device protocols (MQTT and HTTPS) side-by-side** | Feature | [MQTT](mqtt.md) | [HTTPS](http.md) | | --- | --- | --- | | Publish/Subscribe support | Publish and subscribe | Publish only | | SDK support | [AWS Device SDKs](iot-connect-devices.md#iot-connect-device-sdks) support MQTT and WSS protocols | No SDK support, but you can use language-specific methods to make HTTPS requests | | Quality of Service support | [MQTT QoS levels 0 and 1](mqtt.md#mqtt-qos) | QoS is supported by passing a query string parameter ?qos=qos where the value can be 0 or 1. You can add this query string to publish a message with the QoS value you want. | | Can receive messages be missed while device was offline | Yes | No | | `clientId` field support | Yes | No | | Device disconnection detection | Yes | No | | Secure communications | Yes. See [Protocols, port mappings, and authentication](#protocol-mapping) | Yes. See [Protocols, port mappings, and authentication](#protocol-mapping) | | Topic definitions | Application defined | Application defined | | Message data format | Application defined | Application defined | | Protocol overhead | Lower | Higher | | Power consumption | Lower | Higher | ## Choosing an authentication type for your device communication You can configure authentication type for your IoT endpoint using configurable endpoints. Alternatively, use default configuration and determine how your devices authenticate with application protocol, port, and ALPN TLS extension combination. The authentication type you choose determines how your devices will authenticate when connecting to AWS IoT Core. There are five authentication types: **X.509 certificate** Authenticate devices using [X.509 client certificates](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html), which AWS IoT Core validates to authenticate the device. This authentication type works with Secure MQTT (MQTT over TLS) and HTTPS protocols. **X.509 certificate with custom authorizer** Authenticate devices using [X.509 client certificates](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html) and perform additional authentication actions using a [custom authorizer](https://docs.aws.amazon.com//iot/latest/developerguide/config-custom-auth.html), which will receive X.509 client certificate information. This authentication type works with Secure MQTT (MQTT over TLS) and HTTPS protocols. This authentication type is only possible using configurable endpoints with X.509 custom authentication. There is no ALPN option. **AWS Signature Version 4 (SigV4)** Authenticate devices using Cognito or your backend service, supporting social and enterprise federation. This authentication type works with MQTT over WebSocket Secure (WSS) and HTTPS protocols. **Custom authorizer** Authenticate devices by configuring a Lambda function to process custom authentication information sent to AWS IoT Core. This authentication type works with Secure MQTT (MQTT over TLS) , HTTPS, and MQTT over WebSocket Secure (WSS) protocols. **Default** Authenticate devices based on the port and/or application layer protocol negotiation (ALPN) extension that devices use. Some additional authentication options are not supported. For more information, see [Protocols, port mappings, and authentication](#protocol-mapping). The table below shows all the supported combinations of authentication types and application protocols. **Supported combinations of authentication types and application protocols** | Authentication type | Secure MQTT (MQTT over TLS) | MQTT over WebSocket Secure (WSS) | HTTPS | Default | | --- | --- | --- | --- | --- | | X.509 certificate | ✓ | | ✓ | | | X.509 certificate with custom authorizer | ✓ | | ✓ | | | AWS Signature Version 4 (SigV4) | | ✓ | ✓ | | | Custom authorizer | ✓ | ✓ | ✓ | | | Default | | | | ✓ | ## Connection duration limits HTTPS connections aren't guaranteed to last any longer than the time it takes to receive and respond to requests. MQTT connection duration depends on the authentication feature that you use. The following table lists the maximum connection duration under ideal conditions for each feature. **MQTT connection duration by authentication feature** | Feature | Maximum duration \$1 | | --- | --- | | X.509 client certificate | 1–2 weeks | | Custom authentication | 1–2 weeks | | Signature Version 4 | Up to 24 hours | \$1 Not guaranteed With X.509 certificates and custom authentication, connection duration has no hard limit, but it can be as short as a few minutes. Connection interruptions can occur for various reasons. The following list contains some of the most common reasons. + Wi-Fi availability interruptions + Internet service provider (ISP) connection interruptions + Service patches + Service deployments + Service auto scaling + Unavailable service host + Load balancer issues and updates + Client-side errors Your devices must implement strategies for detecting disconnections and reconnecting. For information about disconnect events and guidance on how to handle them, see [Connect/Disconnect events](life-cycle-events.md#connect-disconnect) in [Lifecycle events](life-cycle-events.md). # MQTT [MQTT](http://mqtt.org/) (Message Queuing Telemetry Transport) is a lightweight and widely adopted messaging protocol that is designed for constrained devices. AWS IoT Core support for MQTT is based on the [MQTT v3.1.1 specification](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and the [MQTT v5.0 specification](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), with some differences, as documented in [AWS IoT differences from MQTT specifications](#mqtt-differences). As the latest version of the standard, MQTT 5 introduces several key features that make an MQTT-based system more robust, including new scalability enhancements, improved error reporting with reason code responses, message and session expiry timers, and custom user message headers. For more information about MQTT 5 features that AWS IoT Core supports, see [MQTT 5 supported features](#mqtt5). AWS IoT Core also supports cross MQTT version (MQTT 3 and MQTT 5) communication. An MQTT 3 publisher can send an MQTT 3 message to an MQTT 5 subscriber that will be receiving an MQTT 5 publish message, and vice versa. AWS IoT Core supports device connections that use the MQTT protocol and MQTT over WSS protocol and that are identified by a *client ID*. The [AWS IoT Device SDKs](iot-connect-devices.md#iot-connect-device-sdks) support both protocols and are the recommended ways to connect devices to AWS IoT Core. The AWS IoT Device SDKs support the functions necessary for devices and clients to connect to and access AWS IoT services. The Device SDKs support the authentication protocols that the AWS IoT services require and the connection ID requirements that the MQTT protocol and MQTT over WSS protocols require. For information about how to connect to AWS IoT using the AWS Device SDKs and links to examples of AWS IoT in the supported languages, see [Connecting with MQTT using the AWS IoT Device SDKs](#mqtt-sdk). For more information about authentication methods and the port mappings for MQTT messages, see [Protocols, port mappings, and authentication](protocols.md#protocol-mapping). While we recommend using the AWS IoT Device SDKs to connect to AWS IoT, they are not required. If you do not use the AWS IoT Device SDKs, however, you must provide the necessary connection and communication security. Clients must send the [Server Name Indication (SNI) TLS extension](https://tools.ietf.org/html/rfc3546#section-3.1) in the connection request. Connection attempts that don't include the SNI are refused. For more information, see [Transport Security in AWS IoT](transport-security.html). Clients that use IAM users and AWS credentials to authenticate clients must provide the correct [Signature Version 4](https://docs.aws.amazon.com//general/latest/gr/signature-version-4.html) authentication. After your clients are connected, you can monitor and manage their MQTT client connections using APIs. For more information, see [Managing MQTT connections](#mqtt-client-disconnect). **Topics** + [ ## Connecting with MQTT using the AWS IoT Device SDKs ](#mqtt-sdk) + [ ## MQTT Quality of Service (QoS) options ](#mqtt-qos) + [ ## MQTT persistent sessions ](#mqtt-persistent-sessions) + [ ## MQTT retained messages ](#mqtt-retain) + [ ## MQTT Last Will and Testament (LWT) messages ](#mqtt-lwt) + [ ## Using connectAttributes ](#connect-attribute) + [ ## MQTT 5 supported features ](#mqtt5) + [ ## MQTT 5 properties ](#mqtt5-properties) + [ ## MQTT reason codes ](#mqtt5-reason-codes) + [ ## AWS IoT differences from MQTT specifications ](#mqtt-differences) + [ ## Managing MQTT connections ](#mqtt-client-disconnect) ## Connecting with MQTT using the AWS IoT Device SDKs This section contains links to the AWS IoT Device SDKs and to the source code of sample programs that illustrate how to connect a device to AWS IoT. The sample apps linked here show how to connect to AWS IoT using the MQTT protocol and MQTT over WSS. **Note** The AWS IoT Device SDKs have released an MQTT 5 client. ------ #### [ C\$1\$1 ] **Using the AWS IoT C\$1\$1 Device SDK to connect devices** + [Source code of a sample app that shows an MQTT connection example in C\$1\$1](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt/basic_connect/main.cpp) + [AWS IoT Device SDK for C\$1\$1 v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-cpp-v2) ------ #### [ Python ] **Using the AWS IoT Device SDK for Python to connect devices** + [Source code of a sample app that shows an MQTT connection example in Python](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/master/samples/pubsub.py) + [AWS IoT Device SDK v2 for Python on GitHub](https://github.com/aws/aws-iot-device-sdk-python-v2) ------ #### [ JavaScript ] **Using the AWS IoT Device SDK for JavaScript to connect devices** + [Source code of a sample app that shows an MQTT connection example in JavaScript](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/master/samples/node/pub_sub/index.ts) + [AWS IoT Device SDK for JavaScript v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-js-v2) ------ #### [ Java ] **Using the AWS IoT Device SDK for Java to connect devices** **Note** The AWS IoT Device SDK for Java v2 now supports Android development. For more information, see [AWS IoT Device SDK for Android](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/documents/ANDROID.md). + [Source code of a sample app that shows an MQTT connection example in Java](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/master/samples/BasicPubSub/src/main/java/pubsub/PubSub.java) + [AWS IoT Device SDK for Java v2 on GitHub](https://github.com/aws/aws-iot-device-sdk-java-v2) ------ #### [ Embedded C ] **Using the AWS IoT Device SDK for Embedded C to connect devices** **Important** This SDK is intended for use by experienced embedded-software developers. + [Source code of a sample app that shows an MQTT connection example in Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/demos/mqtt/mqtt_demo_basic_tls/mqtt_demo_basic_tls.c) + [AWS IoT Device SDK for Embedded C on GitHub](https://github.com/aws/aws-iot-device-sdk-embedded-C) ------ ## MQTT Quality of Service (QoS) options AWS IoT and the AWS IoT Device SDKs support the [MQTT Quality of Service (QoS) levels `0` and `1`](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc385349263). The MQTT protocol defines a third level of QoS, level `2`, but AWS IoT does not support it. Only the MQTT protocol supports the QoS feature. HTTPS supports QoS by passing a query string parameter `?qos=qos` where the value can be 0 or 1. This table describes how each QoS level affects messages published to and by the message broker. | With a QoS level of... | The message is... | Comments | | --- | --- | --- | | QoS level 0 | Sent zero or more times | This level should be used for messages that are sent over reliable communication links or that can be missed without a problem. | | QoS level 1 | Sent at least one time, and then repeatedly until a `PUBACK` response is received | The message is not considered complete until the sender receives a `PUBACK` response to indicate successful delivery. | ## MQTT persistent sessions Persistent sessions store a client’s subscriptions and messages, with a Quality of Service (QoS) of 1, that haven't been acknowledged by the client. When the device reconnects to a persistent session, the session resumes, subscriptions are reinstated, and unacknowledged subscribed messages received and stored prior to the reconnection are sent to the client. The processing of the stored messages is recorded in CloudWatch metrics and CloudWatch Logs. For information about the entries written to CloudWatch and CloudWatch Logs, see [Message broker metrics](metrics_dimensions.md#message-broker-metrics) and [Queued log entry](cwl-format.md#log-mb-queued). ### Creating a persistent session In MQTT 3, you create an MQTT persistent session by sending a `CONNECT` message and setting the `cleanSession` flag to `0`. If no session exists for the client sending the `CONNECT` message, a new persistent session is created. If a session already exists for the client, the client resumes the existing session. To create a clean session, you send a `CONNECT` message and set the `cleanSession` flag to `1`, and the broker will not store any session state when the client disconnects. In MQTT 5, you handle persistent sessions by setting the `Clean Start` flag and `Session Expiry Interval`. Clean Start controls the beginning of the connecting session and the end of the previous session. When you set `Clean Start` = `1`, a new session is created and a previous session is terminated if it exists. When you set `Clean Start`= `0`, the connecting session resumes a previous session if it exists. Session Expiry Interval controls the end of the connecting session. Session Expiry Interval specifies the time, in seconds (4-byte integer), that a session will persist after disconnect. Setting `Session Expiry interval`=`0` causes the session to terminate immediately upon disconnect. If the Session Expiry Interval is not specified in the CONNECT message, the default is 0. **MQTT 5 Clean Start and Session Expiry** | Property value | Description | | --- | --- | | Clean Start= 1 | Creates a new session and terminates a previous session if one exists. | | Clean Start= 0 | Resumes a session if a previous session exists. | | Session Expiry Interval> 0 | Persists a session. | | Session Expiry interval= 0 | Does not persist a session. | In MQTT 5, if you set `Clean Start` = `1` and `Session Expiry Interval` = `0`, this is the equivalent of an MQTT 3 clean session. If you set `Clean Start` = `0` and `Session Expiry Interval`> `0`, this is the equivalent of an MQTT 3 persistent session. **Note** Cross MQTT version (MQTT 3 and MQTT 5) persistent sessions are not supported. An MQTT 3 persistent session can't be resumed as an MQTT 5 session, and vice versa. ### Operations during a persistent session Clients use the `sessionPresent` attribute in the connection acknowledged (`CONNACK`) message to determine if a persistent session is present. If `sessionPresent` is `1`, a persistent session is present and any stored messages for the client are delivered to the client after the client receives the `CONNACK`, as described in [Message traffic after reconnection to a persistent session](#persistent-session-reconnect). If `sessionPresent` is `1`, the client does not need to resubscribe. However, if `sessionPresent` is `0`, no persistent session is present and the client must resubscribe to its topic filters. After the client joins a persistent session, it can publish messages and subscribe to topic filters without any additional flags on each operation. ### Message traffic after reconnection to a persistent session A persistent session represents an ongoing connection between a client and an MQTT message broker. When a client connects to the message broker using a persistent session, the message broker saves all subscriptions that the client makes during the connection. When the client disconnects, the message broker stores unacknowledged QoS 1 messages and new QoS 1 messages published to topics to which the client is subscribed. Messages are stored according to account limit. Messages that exceed the limit will be dropped. For more information about persistent message limits, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). When the client reconnects to its persistent session, all subscriptions are reinstated and all stored messages are sent to the client at a maximum rate of 10 messages per second. In MQTT 5, if an outbound QoS 1 with the Message Expiry Interval expires when a client is offline, after the connection resumes, the client won't receive the expired message. After reconnection, the stored messages are sent to the client, at a rate that is limited to 10 stored messages per second, along with any current message traffic until the [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) limit is reached. Because the delivery rate of the stored messages is limited, it will take several seconds to deliver all stored messages if a session has more than 10 stored messages to deliver after reconnection. For shared subscribers, messages will be queued if at least one subscriber of a group uses a persistent session and no subscribers are online to receive the QoS 1 message. Dequeuing of messages is done at a maximum speed of 20 messages per second per active subscriber in a group. For more information, see [shared subscriptions message queuing](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription-queuing). ### Ending a persistent session Persistent sessions can end in the following ways: + The persistent session expiration time elapses. The persistent session expiration timer starts when the message broker detects that a client has disconnected, either by the client disconnecting or the connection timing out. + The client sends a `CONNECT` message that sets the `cleanSession` flag to `1`. + You manually disconnect the client and clear the session using `DeleteConnection` API. For more information, see [Managing MQTT connections](#mqtt-client-disconnect). In MQTT 3, the default value of persistent sessions expiration time is an hour, and this applies to all the sessions in the account. In MQTT 5, you can set the Session Expiry Interval for each session on CONNECT and DISCONNECT packets. For Session Expiry Interval on DISCONNECT packet: + If the current session has a Session Expiry Interval of 0, you can't set Session Expiry Interval to greater than 0 on the DISCONNECT packet. + If the current session has a Session Expiry Interval of greater than 0, and you set the Session Expiry Interval to 0 on the DISCONNECT packet, the session will be ended on DISCONNECT. + Otherwise, the Session Expiry Interval on DISCONNECT packet will update the Session Expiry Interval of the current session. **Note** The stored messages waiting to be sent to the client when a session ends are discarded; however, they are still billed at the standard messaging rate, even though they could not be sent. For more information about message pricing, see [AWS IoT Core Pricing](https://aws.amazon.com/iot-core/pricing). You can configure the expiration time interval. ### Reconnection after a persistent session has expired If a client doesn't reconnect to its persistent session before it expires, the session ends and its stored messages are discarded. When a client reconnects after the session has expired with a `cleanSession` flag to `0`, the service creates a new persistent session. Any subscriptions or messages from the previous session are not available to this session because they were discarded when the previous session expired. ### Persistent session message charges Messages are charged to your AWS account when the message broker sends a message to a client or an offline persistent session. When an offline device with a persistent session reconnects and resumes its session, the stored messages are delivered to the device and charged to your account again. For more information about message pricing, see [AWS IoT Core pricing - Messaging](https://aws.amazon.com/iot-core/pricing/#Messaging). The default persistent session expiration time of one hour can be increased by using the standard limit increase process. Note that increasing the session expiration time might increase your message charges because the additional time could allow for more messages to be stored for the offline device and those additional messages would be charged to your account at the standard messaging rate. The session expiration time is approximate and a session could persist for up to 30 minutes longer than the account limit; however, a session will not be shorter than the account limit. For more information about session limits, see [AWS Service Quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). ## MQTT retained messages AWS IoT Core supports the `RETAIN` flag described in the MQTT protocol. When a client sets the `RETAIN` flag on an MQTT message that it publishes, AWS IoT Core saves the message. It can then be sent to new subscribers, retrieved by calling the [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html) operation, and viewed in the [AWS IoT console](https://console.aws.amazon.com//iot/home#/retainedMessages). **Examples of using MQTT retained messages** + **As an initial configuration message** MQTT retained messages are sent to a client after the client subscribes to a topic. If you want all clients that subscribe to a topic to receive the MQTT retained message right after their subscription, you can publish a configuration message with the `RETAIN` flag set. Subscribing clients also receive updates to that configuration whenever a new configuration message is published. + **As a last-known state message** Devices can set the `RETAIN` flag on current-state messages so that AWS IoT Core will save them. When applications connect or reconnect, they can subscribe to this topic and get the last reported state right after subscribing to the retained message topic. This way they can avoid having to wait until the next message from the device to see the current state. **Topics** + [ ### Common tasks with MQTT retained messages in AWS IoT Core ](#mqtt-retain-using) + [ ### Billing and retained messages ](#mqtt-retain-billing) + [ ### Comparing MQTT retained messages and MQTT persistent sessions ](#mqtt-retain-persist) + [ ### MQTT retained messages and AWS IoT Device Shadows ](#mqtt-retain-shadow) ### Common tasks with MQTT retained messages in AWS IoT Core AWS IoT Core saves MQTT messages with the `RETAIN` flag set. These *retained messages* are sent to all clients that have subscribed to the topic, as a normal MQTT message, and they are also stored to be sent to new subscribers to the topic. MQTT retained messages require specific policy actions to authorize clients to access them. For examples of using retained message policies, see [Retained message policy examples](retained-message-policy-examples.md). This section describes common operations that involve retained messages. + **Creating a retained message** The client determines whether a message is retained when it publishes an MQTT message. Clients can set the `RETAIN` flag when they publish a message by using a [Device SDK](iot-sdks.md). Applications and services can set the `RETAIN` flag when they use the [`Publish` action](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) to publish an MQTT message. Only one message per topic name is retained. A new message with the RETAIN flag set published to a topic replaces any existing retained message that was sent to the topic earlier. **Note** You can't publish to a [reserved topic](reserved-topics.md) with the `RETAIN` flag set. + **Subscribing to a retained message topic** Clients subscribe to retained message topics as they would any other MQTT message topic. Retained messages received by subscribing to a retained message topic have the `RETAIN` flag set. Retained messages are deleted from AWS IoT Core when a client publishes a retained message with a 0-byte message payload to the retained message topic. Clients that have subscribed to the retained message topic will also receive the 0-byte message. Subscribing to a wild card topic filter that includes a retained message topic lets the client receive subsequent messages published to the retained message's topic, but it doesn't deliver the retained message upon subscription. **Note** To receive a retained message upon subscription, the topic filter in the subscription request must match the retained message topic exactly. Retained messages received upon subscribing to a retained message topic have the `RETAIN` flag set. Retained messages that are received by a subscribing client after subscription, don't. + **Retrieving a retained message** Retained messages are delivered to clients automatically when they subscribe to the topic with the retained message. For a client to receive the retained message upon subscription, it must subscribe to the exact topic name of the retained message. Subscribing to a wild card topic filter that includes a retained message topic lets the client receive subsequent messages published to the retained message's topic, but it does not deliver the retained message upon subscription. Services and apps can list and retrieve retained messages by calling [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html) and [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html). A client is not prevented from publishing messages to a retained message topic *without* setting the `RETAIN` flag. This could cause unexpected results, such as the retained message not matching the message received by subscribing to the topic. With MQTT 5, if a retained message has the Message Expiry Interval set and the retained message expires, a new subscriber that subscribes to that topic will not receive the retained message upon successful subscription. + **Listing retained message topics** You can list retained messages by calling [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html) and the retained messages can be viewed in the [AWS IoT console](https://console.aws.amazon.com//iot/home#/retainedMessages). + **Getting retained message details** You can get retained message details by calling [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html) and they can be viewed in the [AWS IoT console](https://console.aws.amazon.com//iot/home#/retainedMessages). + **Retaining a Will message** MQTT [*Will* messages](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag) that are created when a device connects can be retained by setting the `Will Retain` flag in the `Connect Flag bits` field. + **Deleting a retained message** Devices, applications, and services can delete a retained message by publishing a message with the `RETAIN` flag set and an empty (0-byte) message payload to the topic name of the retained message to delete. Such messages delete the retained message from AWS IoT Core, are sent to clients with a subscription to the topic, but they are not retained by AWS IoT Core. Retained messages can also be deleted interactively by accessing the retained message in the [AWS IoT console](https://console.aws.amazon.com//iot/home#/retainedMessages). Retained messages that are deleted by using the [AWS IoT console](https://console.aws.amazon.com//iot/home#/retainedMessages) also send a 0-byte message to clients that have subscribed to the retained message's topic. Retained messages can't be restored after they are deleted. A client would need to publish a new retained message to take the place of the deleted message. + **Debugging and troubleshooting retained messages** The [AWS IoT console](https://console.aws.amazon.com//iot/home#) provides several tools to help you troubleshoot retained messages: + **The **[Retained messages](https://console.aws.amazon.com//iot/home#/retainedMessages)** page** The **Retained messages** page in the AWS IoT console provides a paginated list of the retained messages that have been stored by your Account in the current Region. From this page, you can: + See the details of each retained message, such as the message payload, QoS, the time it was received. + Update the contents of a retained message. + Delete a retained message. + **The **[MQTT test client](https://console.aws.amazon.com//iot/home#/test)**** 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](#mqtt-client-disconnect). Some unexpected results might be the result of these aspects of how retained messages are implemented in AWS IoT Core. + **Retained message limits** When an account has stored the maximum number of retained messages, AWS IoT Core returns a throttled response to messages published with RETAIN set and payloads greater than 0 bytes until some retained messages are deleted and the retained message count falls below the limit. + **Retained message delivery order** The sequence of retained message and subscribed message delivery is not guaranteed. ### Billing and retained messages Publishing messages with the `RETAIN` flag set from a client, by using AWS IoT console, or by calling [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) incurs additional messaging charges described in [AWS IoT Core pricing - Messaging](https://aws.amazon.com//iot-core/pricing/#Messaging). Retrieving retained messages by a client, by using AWS IoT console, or by calling [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html) incurs messaging charges in addition to the normal API usage charges. The additional charges are described in [AWS IoT Core pricing - Messaging](https://aws.amazon.com//iot-core/pricing/#Messaging). MQTT [*Will* messages](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag) that are published when a device disconnects unexpectedly incur messaging charges described in [AWS IoT Core pricing - Messaging](https://aws.amazon.com//iot-core/pricing/#Messaging). For more information about messaging costs, see [AWS IoT Core pricing - Messaging](https://aws.amazon.com//iot-core/pricing/#Messaging). ### Comparing MQTT retained messages and MQTT persistent sessions Retained messages and persistent sessions are standard features of MQTT that make it possible for devices to receive messages that were published while they were offline. Retained messages can be published from persistent sessions. This section describes key aspects of these features and how they work together. | | Retained messages | Persistent sessions | | --- | --- | --- | | **Key features** | Retained messages can be used to configure or notify large groups of devices after they connect. Retained messages can also be used where you want devices to receive only the last message published to a topic after a reconnection. | Persistent sessions are useful for devices that have intermittent connectivity and could miss several important messages. Devices can connect with a persistent session to receive messages sent while they are offline. | | **Examples** | Retained messages can give devices configuration information about their environment when they come online. The initial configuration could include a list of other message topics to which it should subscribe or information about how it should configure its local time zone. | Devices that connect over a cellular network with intermittent connectivity could use persistent sessions to avoid missing important messages that are sent while a device is out of network coverage or needs to turn off its cellular radio. | | **Messages received on initial subscription to a topic** | After subscribing to a topic with a retained message, the most recent retained message is received. | After subscribing to a topic without a retained message, no message is received until one is published to the topic. | | **Subscribed topics after reconnection** | Without a persistent session, the client must subscribe to topics after reconnection. | Subscribed topics are restored after reconnection. | | **Messages received after reconnection** | After subscribing to a topic with a retained message, the most recent retained message is received. | All messages published with a QOS = 1 and subscribed to with a QOS =1 while the device was disconnected are sent after the device reconnects. | | **Data/session expiration** | In MQTT 3, retained messages do not expire. They are stored until they are replaced or deleted. In MQTT 5, retained messages expire after the Message Expiry Interval you set. For more information, see [Message Expiry](#mqtt5). | Persistent sessions expire if the client doesn't reconnect within the timeout period. After a persistent session expires, the client's subscriptions and saved messages that were published with a QOS = 1 and subscribed to with a QOS =1 while the device was disconnected are deleted. Expired messages won't be delivered. For more information about session expirations with persistent sessions, see [MQTT persistent sessions](#mqtt-persistent-sessions). | For information about persistent sessions, see [MQTT persistent sessions](#mqtt-persistent-sessions). With Retained Messages, the publishing client determines whether a message should be retained and delivered to a device after it connects, whether it had a previous session or not. The choice to store a message is made by the publisher and the stored message is delivered to all current and future clients that subscribe to QoS 0 or QoS 1 subscriptions. Retained messages keep only one message on a given topic at a time. When an account has stored the maximum number of retained messages, AWS IoT Core returns a throttled response to messages published with RETAIN set and payloads greater than 0 bytes until some retained messages are deleted and the retained message count falls below the limit. ### MQTT retained messages and AWS IoT Device Shadows Retained messages and Device Shadows both retain data from a device, but they behave differently and serve different purposes. This section describes their similarities and differences. | | Retained messages | Device Shadows | | --- | --- | --- | | **Message payload has a pre-defined structure or schema** | As defined by the implementation. MQTT does not specify a structure or schema for its message payload. | AWS IoT supports a specific data structure. | | **Updating the message payload generates event messages** | Publishing a retained message sends the message to subscribed clients, but doesn't generate additional update messages. | Updating a Device Shadow produces [update messages that describe the change](https://docs.aws.amazon.com//iot/latest/developerguide/device-shadow-mqtt.html#update-delta-pub-sub-topic). | | **Message updates are numbered** | Retained messages are not numbered automatically. | Device Shadow documents have automatic version numbers and timestamps. | | **Message payload is attached to a thing resource** | Retained messages are not attached to a thing resource. | Device Shadows are attached to a thing resource. | | **Updating individual elements of the message payload** | Individual elements of the message can't be changed without updating the entire message payload. | Individual elements of a Device Shadow document can be updated without the need to update the entire Device Shadow document. | | **Client receives message data upon subscription** | The client automatically receives a retained message after it subscribes to a topic with a retained message. | Clients can subscribe to Device Shadow updates, but they must request the current state deliberately. | | **Indexing and searchability** | Retained messages are not indexed for search. | Fleet indexing indexes Device Shadow data for search and aggregation. | ## MQTT Last Will and Testament (LWT) messages Last Will and Testament (LWT) is a feature in MQTT. With LWT, clients can specify a message which the broker will publish to a client-defined topic and send to all clients that subscribed to the topic when an uninitiated disconnection occurs. The message that clients specify is called an LWT message or a Will Message, and the topic that clients define is referred to as a Will Topic. You can specify an LWT message when a device connects to the broker. These messages can be retained by setting the `Will Retain` flag in the `Connect Flag bits` field during the connection. For example, if the `Will Retain` flag is set to `1`, a Will Message will be stored in the broker in the associated Will Topic. For more information, see [Will Messages](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc479576982). When managing client connections, you can control whether LWT messages are published when you disconnect a client. For more information, see [Managing MQTT connections](#mqtt-client-disconnect). The broker will store the Will Messages until an uninitiated disconnection occurs. When that happens, the broker will publish the messages to all clients that subscribed to the Will Topic to notify the disconnection. If the client disconnects from the broker with a client-initiated disconnection using the MQTT DISCONNECT message, the broker won't publish the stored LWT messages. In all other cases, the LWT messages will be dispatched. Due to the asynchronous nature of disconnect processing, LWT messages are not guaranteed to be dispatched in order during reconnection. We recommend that you use [lifecycle events](life-cycle-events.md) to improve the accuracy of connectivity state detection, as these events provide attributes such as timestamps and version numbers to manage out-of-order events. For a complete list of the disconnect scenarios when the broker will send the LWT messages, see [Connect/Disconnect events](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html#connect-disconnect). ## Using connectAttributes `ConnectAttributes` allow you to specify what attributes you want to use in your connect message in your IAM policies such as `PersistentConnect` and `LastWill`. With `ConnectAttributes`, you can build policies that don't give devices access to new features by default, which can be helpful if a device is compromised. `connectAttributes` supports the following features: `PersistentConnect` Use the `PersistentConnect` feature to save all subscriptions the client makes during the connection when the connection between the client and broker is interrupted. `LastWill` Use the `LastWill` feature to publish a message to the `LastWillTopic` when a client unexpectedly disconnects. By default, your policy has a non-persistent connection and there are no attributes passed for this connection. You must specify a persistent connection in your IAM policy if you want to have one. When managing client connections, you can view the connection attributes and session configuration for connected clients. For more information, see [Managing MQTT connections](#mqtt-client-disconnect). For `ConnectAttributes` examples, see [Connect Policy Examples](connect-policy.md). ## MQTT 5 supported features AWS IoT Core support for MQTT 5 is based on the [MQTT v5.0 specification](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) with some differences as documented in [AWS IoT differences from MQTT specifications](#mqtt-differences). **Topics** + [ ### Shared subscriptions ](#mqtt5-shared-subscription) + [ ### Clean Start and Session Expiry ](#mqtt5-clean-start) + [ ### Reason code on all ACKs ](#mqtt5-reason-code) + [ ### Topic aliases ](#mqtt5-topic-alias) + [ ### Message expiry ](#mqtt5-message-expiry) + [ ### Other MQTT 5 features ](#mqtt5-other-features) ### Shared subscriptions AWS IoT Core supports shared subscriptions for both MQTT 3.1.1 and MQTT 5. Shared subscriptions allow multiple clients to share a subscription to a topic and only one client will receive messages published to that topic using a random distribution. Shared subscriptions can effectively load balance MQTT messages across a number of subscribers. For example, say you have 1,000 devices publishing to the same topic, and 10 backend applications processing those messages. In that case, the backend applications can subscribe to the same topic, and each would randomly receive messages published by the devices to the shared topic. This is effectively "sharing" the load of those messages. Shared subscriptions also allow for better resiliency. When any backend application disconnects, the broker distributes the load to remaining subscribers in the group. When all the subscribers disconnect, messages are queued. Message queuing capabilities are available for shared subscriptions on both MQTT 3.1.1 and MQTT 5 connections to enhance message delivery reliability. To use shared subscriptions, clients subscribe to a shared subscription's [topic filter](https://docs.aws.amazon.com//iot/latest/developerguide/topics.html#topicfilters) as follows: ``` $share/{ShareName}/{TopicFilter} ``` + `$share` is a literal string to indicate a Shared Subscription's topic filter, which must start with `$share`. + `{ShareName}` is a character string to specify the shared name used by a group of subscribers. A shared subscription's topic filter must contain a `ShareName` and be followed by the `/` character. The `{ShareName}` must not include the following characters: `/`, `+`, or `#`. The maximum size for `{ShareName}` is 128 UTF-8 characters. + `{TopicFilter}` follows the same [topic filter](https://docs.aws.amazon.com//iot/latest/developerguide/topics.html#topicfilters) syntax as a non-shared subscription. The maximum size for `{TopicFilter}` is 256 UTF-8 characters. + The two required slashes (`/`) for `$share/{ShareName}/{TopicFilter}` are not included in the [Maximum number of slashes in topic and topic filter](https://console.aws.amazon.com/servicequotas/home/services/iotcore/quotas/L-AD5A8D4F) limit. Subscriptions that have the same `{ShareName}/{TopicFilter}` belong to the same shared subscription group. You can create multiple shared subscription groups and don't exceed the [Shared Subscriptions per group limit](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). For more information, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html) from the *AWS General Reference*. The following tables compare non-shared subscriptions and shared subscriptions: **** | Subscription | Description | Topic filter examples | | --- | --- | --- | | Non-shared subscriptions | Each client creates a separate subscription to receive the published messages. When a message is published to a topic, all subscribers to that topic receive a copy of the message. | 
sports/tennis
sports/#
| | Shared subscriptions | Multiple clients can share a subscription to a topic and only one client will receive messages published to that topic at a random distribution. | 
$share/consumer/sports/tennis
$share/consumer/sports/#
| **** | Non-shared subscriptions flow | Shared subscriptions flow | | --- | --- | | ![\[Regular subscriptions for both MQTT 3 and MQTT 5 in AWS IoT Core.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/mqtt_regular_subscription.gif) | ![\[Shared subscriptions for both MQTT 3 and MQTT 5 in AWS IoT Core.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/mqtt_shared_subscription.gif) | **Important notes for using shared subscriptions** + If the shared subscriber group consists of any persistent session subscribers, when all the subscribers in the shared group are disconnected, or if any subscribers breach the Publish requests per second per connection limit, any unacknowledged QoS 1 messages and undelivered QoS 1 messages published to a shared subscription group will be queued. For more information, see [shared subscriptions message queuing](#mqtt5-shared-subscription-message-queuing). + QoS 0 messages published to a shared subscription group will be dropped upon any failure. + Shared subscriptions don't receive [retained messages](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html#mqtt-retain) when subscribing to topic patterns as part of a shared subscriber group. Messages that are published on topics that have shared subscribers and have the `RETAIN` flag set are delivered to shared subscribers like any other publish message. + When shared subscriptions contain wildcard characters (\$1 or \$1), there might be multiple matching shared subscriptions to a topic. If that happens, the message broker copies the publishing message and sends it to a random client in each matching shared subscription. The wildcard behavior of shared subscriptions can be explained in the following diagram. ![\[Shared subscriptions with wildcard characters in AWS IoT Core.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/mqtt_shared_subscriptions_wildcard.gif) In this example, there are three matching shared subscriptions to the publishing MQTT topic `sports/tennis`. The message broker copies the published message and sends the message to a random client in each matching group. Client 1 and client 2 share the subscription: `$share/consumer1/sports/tennis` Client 3 and client 4 share the subscription: `$share/consumer1/sports/#` 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.md#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](#mqtt-client-disconnect). 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. #### Shared subscriptions message queuing To enhance message delivery reliability, shared subscriptions include message queuing capabilities that store messages when no online subscribers are available. When a shared subscription group contains at least one member with a persistent session, the queuing feature is enabled for the group. When distributing messages, online members are selected as recipients. QoS 1 messages are queued when no members are found online or when subscribers exceed the [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) limit. Queued messages are delivered when either existing members resume their persistent sessions, or new members join the group. Queued messages are delivered at up to 20 queued messages per second per active group subscriber, along with any other messages delivered to the subscriber as per the subscriptions. By default, queued message retention follows the [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) quota. However, if a Message Expiry Interval (MEI) is set in the inbound publish message, the MEI takes precedence. When MEI is present, it determines the message retention period, regardless of the Persistent Session expiry period. Message queue rates are limited according to the [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) quota, and the number of messages is limited by the [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) quota. To view and manage your quotas, access the [Service Quotas console](https://console.aws.amazon.com/servicequotas/home). You can monitor the Queue CloudWatch by searching for `ApproximateQueueDepth` under the `AWS/Usage` namespace, or you can use the following CLI command to list the metrics associated with each shared subscription group's queue depth. ``` aws cloudwatch list-metrics --namespace "AWS/Usage" --dimensions Name=Resource,Value='ApproximateQueueDepth' ``` When these limits are exceeded, only the messages that were already queued before reaching the limit are retained. New incoming messages that would exceed the limits are dropped. The system does not replace older queued messages with newer ones. The queuing of messages is recorded in CloudWatch metrics and CloudWatch Logs. For information about the entries written to CloudWatch and CloudWatch Logs, see [Message broker metrics](metrics_dimensions.md#message-broker-metrics) and [Queued log entry](cwl-format.md#log-mb-queued). Queued messages are still billed at the standard messaging rate. For more information about message pricing, see [AWS IoT Core Pricing](https://aws.amazon.com/iot-core/pricing). **Session lifecycle in shared subscription group** When a clean session subscribes to a group, it becomes an online member of the group. When it unsubscribes or disconnects, the clean session leaves the group. When a persistent session subscribes to a group, it becomes an online member of the group. When it disconnects, it still remains in the group, but becomes an offline member of the group. When it reconnects, it becomes an online member again. The persistent session leaves the group when it explicitly unsubscribes or when it expires after disconnect. ### Clean Start and Session Expiry You can use Clean Start and Session Expiry to handle your persistent sessions with more flexibility. A Clean Start flag indicates whether the session should start without using an existing session. A Session Expiry interval indicates how long to retain the session after a disconnect. The session expiry interval can be modified at disconnect. For more information, see [MQTT persistent sessions](#mqtt-persistent-sessions). ### Reason code on all ACKs You can debug or process error messages more easily using the reason codes. Reason codes are returned by the message broker based on the type of interaction with the broker (Subscribe, Publish, Acknowledge). For more information, see [MQTT reason codes](#mqtt5-reason-codes). For a complete list of MQTT reason codes, see [MQTT v5 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901031). ### Topic aliases You can substitute a topic name with a topic alias, which is a two-byte integer. Using topic aliases can optimize the transmission of topic names to potentially reduce data costs on metered data services. AWS IoT Core has a default limit of 8 topic aliases. For more information, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html) from the *AWS General Reference*. ### Message expiry You can add message expiry values to published messages. These values represent the Message Expiry Interval (MEI) in seconds. If the messages haven't been sent to the subscribers within that interval, the message will expire and be removed. If you don't set the message expiry value, the message will not expire. On the outbound, the subscriber will receive a message with the remaining time left in the expiry interval. For example, if an inbound publish message has a message expire of 30 seconds, and it's routed to the subscriber after 20 seconds, the message expiry field will be updated to 10. It is possible for the message received by the subscriber to have an updated MEI of 0. This is because as soon as the time remaining is 999 ms or less, it will be updated to 0. In AWS IoT Core, the minimum MEI is 1. If the interval is set to 0 from the client side, it will be adjusted to 1. The maximum message expiry interval is 604800 (7 days). Any values higher than this will be adjusted to the maximum value. In cross version communication, the behavior of message expiry is decided by MQTT version of the inbound publish message. For example, a message with message expiry sent by a session connected via MQTT5 can expire for devices subscribed with MQTT3 sessions. The table below lists how message expiry supports the following types of publish messages: **** | Publish Message Type | Message Expiry Interval | | --- | --- | | Regular Publish | If a server fails to deliver the message within the specified time, the expired message will be removed and the subscriber won't receive it. This includes situations such as when a device is not pubacking their QoS 1 messages. | | Retain | If a retained message expires and a new client subscribes to the topic, the client won't receive the message upon subscription. | | Last Will | The interval for last will messages starts after the client disconnects and the server attempts to deliver the last will message to its subscribers. | | Queued messages | If an outbound QoS 1 with Message Expiry Interval expires when a client is offline, after the [persistent session](#mqtt-persistent-sessions) resumes, the client won't receive the expired message. | ### Other MQTT 5 features **Server disconnect** When a disconnection happens, the server can proactively send the client a DISCONNECT to notify connection closure with a reason code for disconnection. **Request/Response** Publishers can request a response be sent by the receiver to a publisher-specified topic upon reception. **Maximum Packet Size** Client and Server can independently specify the maximum packet size that they support. **Payload format and content type** You can specify the payload format (binary, text) and content type when a message is published. These are forwarded to the receiver of the message. ## MQTT 5 properties MQTT 5 properties are important additions to the MQTT standard to support new MQTT 5 features such as Session Expiry and the Request/Response pattern. In AWS IoT Core, you can create [rules](https://docs.aws.amazon.com//iot/latest/developerguide/republish-rule-action.html) that can forward the properties in outbound messages, or use [HTTP Publish](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) to publish MQTT messages with some of the new properties. The following table lists all the MQTT 5 properties that AWS IoT Core supports. | Property | Description | Input type | Packet | | --- | --- | --- | --- | | Payload Format Indicator | A Boolean value that indicates whether the payload is formatted as UTF-8. | Byte | PUBLISH, CONNECT | | Content Type | A UTF-8 string that describes the content of the payload. | UTF-8 string | PUBLISH, CONNECT | | Response Topic | A UTF-8 string that describes the topic the receiver should publish to as part of the request-response flow. The topic must not have wildcard characters. | UTF-8 string | PUBLISH, CONNECT | | Correlation Data | Binary data used by the sender of the request message to identify which request the response message is for. | Binary | PUBLISH, CONNECT | | User Property | A UTF-8 string pair. This property can appear multiple times in one packet. Receivers will receive the key-value pairs in the same order they are sent. | UTF-8 string pair | CONNECT, PUBLISH, Will Properties, SUBSCRIBE, DISCONNECT, UNSUBSCRIBE | | Message Expiry Interval | A 4-byte integer that represents the Message Expiry Interval in seconds. If absent, the message doesn't expire. | 4-byte integer | PUBLISH, CONNECT | | Session Expiry Interval | A 4-byte integer that represents the session expiry interval in seconds. AWS IoT Core supports a maximum of 7 days, with a default maximum of one hour. If the value you set exceeds the maximum of your account, AWS IoT Core will return the adjusted value in the CONNACK. | 4-byte integer | CONNECT, CONNACK, DISCONNECT | | Assigned Client Identifier | A random client ID generated by AWS IoT Core when a client ID isn’t specified by devices. The random client ID must be a new client identifier that's not used by any other session currently managed by the broker. | UTF-8 string | CONNACK | | Server Keep Alive | A 2-byte integer that represents the keep alive time assigned by the server. The server will disconnect the client if the client is inactive for more than the keep alive time. | 2-byte integer | CONNACK | | Request Problem Information | A Boolean value that indicates whether the Reason String or User Properties are sent in the case of failures. | Byte | CONNECT | | Receive Maximum | A 2-byte integer that represents the maximum number of PUBLISH QOS > 0 packets which can be sent without receiving an PUBACK. | 2-byte integer | CONNECT, CONNACK | | Topic Alias Maximum | This value indicates the highest value that will be accepted as a Topic Alias. Default is 0. | 2-byte integer | CONNECT, CONNACK | | Maximum QoS | The maximum value of QoS that AWS IoT Core supports. Default is 1. AWS IoT Core doesn't support QoS 2. | Byte | CONNACK | | Retain Available | A Boolean value that indicates whether AWS IoT Core message broker supports retained messages. The default is 1. | Byte | CONNACK | | Maximum Packet Size | The maximum packet size that AWS IoT Core accepts and sends. Cannot exceed 128 KB. | 4-byte integer | CONNECT, CONNACK | | Wildcard Subscription Available | A Boolean value that indicates whether AWS IoT Core message broker supports Wildcard Subscription Available. The default is 1. | Byte | CONNACK | | Subscription Identifier Available | A Boolean value that indicates whether AWS IoT Core message broker supports Subscription Identifier Available. The default is 0. | Byte | CONNACK | ## MQTT reason codes 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). **CONNACK Reason Codes** | Value | Hex | Reason Code name | Description | | --- | --- | --- | --- | | 0 | 0x00 | Success | The connection is accepted. | | 128 | 0x80 | Unspecified error | The server does not wish to reveal the reason for the failure, or none of the other reason codes apply. | | 133 | 0x85 | Client Identifier not valid | The client identifier is a valid string but is not allowed by the server. | | 134 | 0x86 | Bad User Name or Password | The server does not accept the user name or password specified by the client. | | 135 | 0x87 | Not authorized | The client is not authorized to connect. | | 144 | 0x90 | Topic Name invalid | The Will Topic Name is correctly formed but is not accepted by the server. | | 151 | 0x97 | Quota exceeded | An implementation or administrative imposed limit has been exceeded. | | 155 | 0x9B | QoS not supported | The server does not support the QoS set in Will QoS. | **PUBACK Reason Codes** | Value | Hex | Reason Code name | Description | | --- | --- | --- | --- | | 0 | 0x00 | Success | The message is accepted. Publication of the QoS 1 message proceeds. | | 128 | 0x80 | Unspecified error | The receiver does not accept the publish, but either does not want to reveal the reason, or it does not match one of the other values. | | 135 | 0x87 | Not authorized | The PUBLISH is not authorized. | | 144 | 0x90 | Topic Name invalid | The topic name is not malformed, but is not accepted by the client or server. | | 145 | 0x91 | Packet identifier in use | The packet identifier is already in use. This might indicate a mismatch in the session state between the client and server. | | 151 | 0x97 | Quota exceeded | An implementation or administrative imposed limit has been exceeded. | **DISCONNECT Reason Codes** | Value | Hex | Reason Code name | Description | | --- | --- | --- | --- | | 129 | 0x81 | Malformed Packet | The received packet does not conform to this specification. | | 130 | 0x82 | Protocol Error | An unexpected or out of order packet was received. | | 135 | 0x87 | Not authorized | The request is not authorized. | | 139 | 0x8B | Server shutting down | The server is shutting down. | | 141 | 0x8D | Keep Alive timeout | The connection is closed because no packet has been received for 1.5 times the Keep Alive time. | | 142 | 0x8E | Session taken over | Another connection using the same ClientID has connected, causing this connection to be closed. | | 143 | 0x8F | Topic Filter invalid | The topic filter is correctly formed but is not accepted by the server. | | 144 | 0x90 | Topic Name invalid | The topic name is correctly formed but is not accepted by this client or server. | | 147 | 0x93 | Receive Maximum exceeded | The client or server has received more than the Receive Maximum publication for which it has not sent PUBACK or PUBCOMP. | | 148 | 0x94 | Topic Alias invalid | The client or server has received a PUBLISH packet containing a topic alias greater than the Maximum Topic Alias it sent in the CONNECT or CONNACK packet. | | 151 | 0x97 | Quota exceeded | An implementation or administrative imposed limit has been exceeded. | | 152 | 0x98 | Administrative action | The connection is closed due to an administrative action. | | 155 | 0x9B | QoS not supported | The client specified a QoS greater than the QoS specified in a Maximum QoS in the CONNACK. | | 161 | 0xA1 | Subscription Identifiers not supported | The server does not support subscription identifiers; the subscription is not accepted. | **SUBACK Reason Codes** | Value | Hex | Reason Code name | Description | | --- | --- | --- | --- | | 0 | 0x00 | Granted QoS 0 | The subscription is accepted and the maximum QoS sent will be QoS 0. This might be a lower QoS than was requested. | | 1 | 0x01 | Granted QoS 1 | The subscription is accepted and the maximum QoS sent will be QoS 1. This might be a lower QoS than was requested. | | 128 | 0x80 | Unspecified error | The subscription is not accepted and the Server either does not wish to reveal the reason or none of the other Reason Codes apply. | | 135 | 0x87 | Not authorized | The Client is not authorized to make this subscription. | | 143 | 0x8F | Topic Filter invalid | The Topic Filter is correctly formed but is not allowed for this Client. | | 145 | 0x91 | Packet Identifier in use | The specified Packet Identifier is already in use. | | 151 | 0x97 | Quota exceeded | An implementation or administrative imposed limit has been exceeded. | **UNSUBACK Reason Codes** | Value | Hex | Reason Code name | Description | | --- | --- | --- | --- | | 0 | 0x00 | Success | The subscription is deleted. | | 128 | 0x80 | Unspecified error | The unsubscribe could not be completed and the Server either does not wish to reveal the reason or none of the other Reason Codes apply. | | 143 | 0x8F | Topic Filter invalid | The Topic Filter is correctly formed but is not allowed for this Client. | | 145 | 0x91 | Packet Identifier in use | The specified Packet Identifier is already in use. | ## AWS IoT differences from MQTT specifications The message broker implementation is based on the [MQTT v3.1.1 specification](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and the [MQTT v5.0 specification](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), but it differs from the specifications in these ways: + AWS IoT doesn't support the following packets for MQTT 3: PUBREC, PUBREL, and PUBCOMP. + AWS IoT doesn't support the following packets for MQTT 5: PUBREC, PUBREL, PUBCOMP, and AUTH. + AWS IoT doesn't support MQTT 5 server redirection. + AWS IoT supports MQTT quality of service (QoS) levels 0 and 1 only. AWS IoT doesn't support publishing or subscribing with QoS level 2. When QoS level 2 is requested, the message broker doesn't send a PUBACK or SUBACK. + In AWS IoT, subscribing to a topic with QoS level 0 means that a message is delivered zero or more times. A message might be delivered more than once. Messages delivered more than once might be sent with a different packet ID. In these cases, the DUP flag is not set. + When responding to a connection request, the message broker sends a CONNACK message. This message contains a flag to indicate if the connection is resuming a previous session. + Before sending additional control packets or a disconnect request, the client must wait for the CONNACK message to be received on their device from the AWS IoT message broker. + When a client subscribes to a topic, there might be a delay between the time the message broker sends a SUBACK and the time the client starts receiving new matching messages. + When a client uses the wildcard character `#` in the topic filter to subscribe to a topic, all strings at and below its level in the topic hierarchy are matched. However, the parent topic is not matched. For example, a subscription to the topic `sensor/#` receives messages published to the topics `sensor/`, `sensor/temperature`, `sensor/temperature/room1`, but not messages published to `sensor`. For more information about wildcards, see [Topic name filters](topics.md#topicfilters). + 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](#mqtt-client-disconnect). + On rare occasions, the message broker might resend the same logical PUBLISH message with a different packet ID. + Subscription to topic filters that contain a wildcard character can't receive retained messages. To receive a retained message, the subscribe request must contain a topic filter that matches the retained message topic exactly. + The message broker doesn't guarantee the order in which messages and ACK are received. + 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*. + The MQTT DUP flag is not supported. ## 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.md) 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 (\$1). 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/?cleanSession=&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 (\$1) 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. # HTTPS publish Clients can publish messages by making requests to the REST API using the HTTP 1.0 or 1.1 protocols. For the authentication and port mappings used by HTTP requests, see [Protocols, port mappings, and authentication](protocols.md#protocol-mapping). **Note** HTTPS doesn't support a `clientId` value like MQTT does. `clientId` is available when using MQTT, but it's not available when using HTTPS. ## HTTPS message URL Devices and clients publish their messages by making POST requests to a client-specific endpoint and a topic-specific URL: ``` https://IoT_data_endpoint/topics/url_encoded_topic_name?qos=1 ``` + *IoT\$1data\$1endpoint* is the [AWS IoT device data endpoint](iot-connect-devices.md#iot-connect-device-endpoints). You can find the endpoint in the AWS IoT console on the thing's details page or on the client by using the AWS CLI command: ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` The endpoint should look something like this: `a3qjEXAMPLEffp-ats.iot.us-west-2.amazonaws.com` + *url\$1encoded\$1topic\$1name* is the full [topic name](topics.md#topicnames) of the message being sent. ## HTTPS message code examples These are some examples of how to send an HTTPS message to AWS IoT. ------ #### [ Python (port 8443) ] ``` import requests import argparse # define command-line parameters parser = argparse.ArgumentParser(description="Send messages through an HTTPS connection.") parser.add_argument('--endpoint', required=True, help="Your AWS IoT data custom endpoint, not including a port. " + "Ex: \"abcdEXAMPLExyz-ats.iot.us-east-1.amazonaws.com\"") parser.add_argument('--cert', required=True, help="File path to your client certificate, in PEM format.") parser.add_argument('--key', required=True, help="File path to your private key, in PEM format.") parser.add_argument('--topic', required=True, default="test/topic", help="Topic to publish messages to.") parser.add_argument('--message', default="Hello World!", help="Message to publish. " + "Specify empty string to publish nothing.") # parse and load command-line parameter values args = parser.parse_args() # create and format values for HTTPS request publish_url = 'https://' + args.endpoint + ':8443/topics/' + args.topic + '?qos=1' publish_msg = args.message.encode('utf-8') # make request publish = requests.request('POST', publish_url, data=publish_msg, cert=[args.cert, args.key]) # print results print("Response status: ", str(publish.status_code)) if publish.status_code == 200: print("Response body:", publish.text) ``` ------ #### [ Python (port 443) ] ``` import requests import http.client import json import ssl ssl_context = ssl.SSLContext(protocol=ssl.PROTOCOL_TLS_CLIENT) ssl_context.minimum_version = ssl.TLSVersion.TLSv1_2 # note the use of ALPN ssl_context.set_alpn_protocols(["x-amzn-http-ca"]) ssl_context.load_verify_locations(cafile="./") # update the certificate and the AWS endpoint ssl_context.load_cert_chain("./", "") connection = http.client.HTTPSConnection('', 443, context=ssl_context) message = {'data': 'Hello, I'm using TLS Client authentication!'} json_data = json.dumps(message) connection.request('POST', '/topics/device%2Fmessage?qos=1', json_data) # make request response = connection.getresponse() # print results print(response.read().decode()) ``` ------ #### [ CURL ] You can use [curl](https://curl.haxx.se) from a client or device to send a message to AWS IoT. **To use curl to send a message from an AWS IoT client device** 1. Check the **curl** version. 1. On your client, run this command at a command prompt. **curl --help** In the help text, look for the TLS options. You should see the `--tlsv1.2` option. 1. If you see the `--tlsv1.2` option, continue. 1. If you don't see the `--tlsv1.2` option or you get a `command not found` error, you might need to update or install curl on your client or install `openssl` before you continue. 1. Install the certificates on your client. Copy the certificate files that you created when you registered your client (thing) in the AWS IoT console. Make sure you have these three certificate files on your client before you continue. + The CA certificate file (*Amazon-root-CA-1.pem* in this example). + The client's certificate file (*device.pem.crt* in this example). + The client's private key file (*private.pem.key* in this example). 1. Create the **curl** command line, replacing the replaceable values for those of your account and system. ``` curl --tlsv1.2 \ --cacert Amazon-root-CA-1.pem \ --cert device.pem.crt \ --key private.pem.key \ --request POST \ --data "{ \"message\": \"Hello, world\" }" \ "https://IoT_data_endpoint:8443/topics/topic?qos=1" ``` --tlsv1.2 Use TLS 1.2 (SSL). --cacert *Amazon-root-CA-1.pem* The file name and path, if necessary, of the CA certificate to verify the peer. --cert *device.pem.crt* The client's certificate file name and path, if necessary. --key *private.pem.key* The client's private key file name and path, if necessary. --request POST The type of HTTP request (in this case, POST). --data "*\$1 \$1"message\$1": \$1"Hello, world\$1" \$1*" The HTTP POST data you want to publish. In this case, it's a JSON string, with the internal quotation marks escaped with the backslash character (\$1). "https://*IoT\$1data\$1endpoint*:8443/topics/*topic*?qos=1" The URL of your client's AWS IoT device data endpoint, followed by the HTTPS port, `:8443`, which is then followed by the keyword, `/topics/` and the topic name, `topic`, in this case. Specify the Quality of Service as the query parameter, `?qos=1`. 1. Open the MQTT test client in the AWS IoT console. Follow the instructions in [View MQTT messages with the AWS IoT MQTT client](view-mqtt-messages.md) and configure the console to subscribe to messages with the topic name of *topic* used in your **curl** command, or use the wildcard topic filter of `#`. 1. Test the command. While monitoring the topic in the test client of the AWS IoT console, go to your client and issue the curl command line that you created in step 3. You should see your client's messages in the console. ------ # MQTT topics MQTT topics identify AWS IoT messages. AWS IoT clients identify the messages they publish by giving the messages topic names. Clients identify the messages to which they want to subscribe (receive) by registering a topic filter with AWS IoT Core. The message broker uses topic names and topic filters to route messages from publishing clients to subscribing clients. The message broker uses topics to identify messages sent using MQTT and sent using HTTP to the [HTTPS message URL](http.md#httpurl). While AWS IoT supports some [reserved system topics](reserved-topics.md), most MQTT topics are created and managed by you, the system designer. AWS IoT uses topics to identify messages received from publishing clients and select messages to send to subscribing clients, as described in the following sections. Before you create a topic namespace for your system, review the characteristics of MQTT topics to create the hierarchy of topic names that works best for your IoT system. ## Topic names Topic names and topic filters are UTF-8 encoded strings. They can represent a hierarchy of information by using the forward slash (/) character to separate the levels of the hierarchy. For example, this topic name could refer to a temperature sensor in room 1: + `sensor/temperature/room1` In this example, there might also be other types of sensors in other rooms with topic names such as: + `sensor/temperature/room2` + `sensor/humidity/room1` + `sensor/humidity/room2` **Note** As you consider topic names for the messages in your system, keep in mind: Topic names and topic filters are case sensitive. Topic names must not contain personally identifiable information. Topic names that begin with a \$1 are [reserved topics](reserved-topics.md) to be used only by AWS IoT Core. AWS IoT Core can't send or receive messages between AWS accounts or Regions. For more information on designing your topic names and namespace, see our whitepaper, [Designing MQTT Topics for AWS IoT Core](https://docs.aws.amazon.com/whitepapers/latest/designing-mqtt-topics-aws-iot-core/designing-mqtt-topics-aws-iot-core.html). For examples of how apps can publish and subscribe to messages, start with [Getting started with AWS IoT Core tutorials](iot-gs.md) and [AWS IoT Device SDKs, Mobile SDKs, and AWS IoT Device Client](iot-sdks.md). **Important** The topic namespace is limited to an AWS account and Region. For example, the `sensor/temp/room1` topic used by an AWS account in one Region is distinct from the `sensor/temp/room1` topic used by the same AWS account in another Region or used by any other AWS account in any Region. ## Topic ARN All topic ARNs (Amazon Resource Names) have the following form: ``` arn:aws:iot:aws-region:AWS-account-ID:topic/Topic ``` For example, `arn:aws:iot:us-west-2:123EXAMPLE456:topic/application/topic/device/sensor` is an ARN for the topic ` application/topic/device/sensor`. ## Topic name filters Subscribing clients register topic name filters with the message broker to specify the message topics that the message broker should send to them. A topic name filter can be a single topic name to subscribe to a single topic name or it can include wildcard characters to subscribe to multiple topic names at the same time. Publishing clients can't use wildcard characters in the topic names they publish. The following table lists the wildcard characters that can be used in a topic filter. **Topic wildcards** | Wildcard character | Matches | Notes | | --- | --- | --- | | \$1 | All strings at and below its level in the topic hierarchy. | Must be the last character in the topic filter. Must be the only character in its level of the topic hierarchy. Can be used in a topic filter that also contains the \$1 wildcard character. | | \$1 | Any string in the level that contains the character. | Must be the only character in its level of the topic hierarchy. Can be used in multiple levels of a topic filter. | Using wildcards with the previous sensor topic name examples: + A subscription to `sensor/#` receives messages published to `sensor/`, `sensor/temperature`, `sensor/temperature/room1`, but not messages published to `sensor`. + A subscription to `sensor/+/room1` receives messages published to `sensor/temperature/room1` and `sensor/humidity/room1`, but not messages sent to `sensor/temperature/room2` or `sensor/humidity/room2`. ### Topic filter ARN All topic filter ARNs (Amazon Resource Names) have the following form: ``` arn:aws:iot:aws-region:AWS-account-ID:topicfilter/TopicFilter ``` For example, `arn:aws:iot:us-west-2:123EXAMPLE456:topicfilter/application/topic/+/sensor` is an ARN for the topic filter` application/topic/+/sensor`. # MQTT message payload The message payload that is sent in your MQTT messages isn't specified by AWS IoT, unless it's for one of the [Reserved topics](reserved-topics.md). To accommodate your application's needs, we recommend you define the message payload for your topics within the constraints of the [AWS IoT Core Service Quotas for Protocols](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-protocol-limits). Using a JSON format for your message payload enables the AWS IoT rules engine to parse your messages and apply SQL queries to it. If your application doesn't require the rules engine to apply SQL queries to your message payloads, you can use any data format that your application requires. For information about limitations and reserved characters in a JSON document used in SQL queries, see [JSON extensions](iot-sql-json.md). For more information about designing your MQTT topics and their corresponding message payloads, see [Designing MQTT Topics for AWS IoT Core](https://docs.aws.amazon.com/whitepapers/latest/designing-mqtt-topics-aws-iot-core/designing-mqtt-topics-aws-iot-core.html). If a message size limit exceeds the service quotas, it will result in a `CLIENT_ERROR` with reason `PAYLOAD_LIMIT_EXCEEDED` and "Message payload exceeds size limit for message type." For more information about message size limit, see [AWS IoT Core message broker limits and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits.html). # Reserved topics Topics that begin with a dollar sign (\$1) are reserved for use by AWS IoT. You can subscribe and publish to these reserved topics as they allow; however, you can't create new topics that begin with a dollar sign. Unsupported publish or subscribe operations to reserved topics can result in a terminated connection. ## Asset model topics | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/sitewise/asset-models/*assetModelId*/assets/*assetId*/properties/*propertyId* | Subscribe | AWS IoT SiteWise publishes asset property notifications to this topic. For more information, see [Interacting with other AWS services](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/interact-with-other-services.html) in the *AWS IoT SiteWise User Guide*. | ## AWS IoT Device Defender topics These messages support response buffers in Concise Binary Object Representation (CBOR) format and JavaScript Object Notation (JSON), depending on the *payload-format* of the topic. AWS IoT Device Defender topics only support MQTT publish. | *payload-format* | Response format data type | | --- | --- | | cbor | Concise Binary Object Representation (CBOR) | | json | JavaScript Object Notation (JSON) | For more information, see [Sending metrics from devices](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/detect-device-side-metrics.html#DetectMetricsMessages). | Topic | Allowed operations | Description | | --- | --- | --- | | \$1aws/things/*thingName*/defender/metrics/*payload-format* | Publish | AWS IoT Device Defender agents publish metrics to this topic. For more information, see [Sending metrics from devices](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/detect-device-side-metrics.html#DetectMetricsMessages). | | \$1aws/things/*thingName*/defender/metrics/*payload-format*/accepted | Subscribe | AWS IoT publishes to this topic after a AWS IoT Device Defender agent publishes a successful message to \$1aws/things/*thingName*/defender/metrics/*payload-format*. For more information, see [Sending metrics from devices](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/detect-device-side-metrics.html#DetectMetricsMessages). | | \$1aws/things/*thingName*/defender/metrics/*payload-format*/rejected | Subscribe | AWS IoT publishes to this topic after a AWS IoT Device Defender agent publishes an unsuccessful message to \$1aws/things/*thingName*/defender/metrics/*payload-format*. For more information, see [Sending metrics from devices](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/detect-device-side-metrics.html#DetectMetricsMessages). | ## AWS IoT Core Device Location topics AWS IoT Core Device Location can resolve the measurement data from your device and provide an estimated location of your IoT devices. The measurement data from the device can include GNSS, Wi-Fi, cellular, and IP address. AWS IoT Core Device Location then chooses the measurement type that provides the best accuracy and solves the device location information. For more information, see [AWS IoT Core Device Location](device-location.md) and [Resolving device location using AWS IoT Core Device Location MQTT topics](device-location-reserved-topics.md). | Topic | Allowed operations | Description | | --- | --- | --- | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate | Publish | A device publishes to this topic to get the scanned raw measurement data to be resolved by AWS IoT Core Device Location. | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate/accepted | Subscribe | AWS IoT Core Device Location publishes to this topic after it has resolved the device location successfully. | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate/rejected | Subscribe | AWS IoT Core Device Location publishes to this topic when it is unable to resolve the device location successfully due to 4xx errors. | ## Event topics The event messages are published when certain events occur. For example, events are generated by the registry when things are added, updated, or deleted. The table shows the various AWS IoT events and their reserved topics. | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/events/certificates/registered/*caCertificateId* | Subscribe | AWS IoT publishes this message when AWS IoT automatically registers a certificate and when a client presents a certificate with the `PENDING_ACTIVATION` status. For more information, see [Configure the first connection by a client for automatic registration](auto-register-device-cert.md#configure-auto-reg-first-connect). | | \$1aws/events/job/*jobID*/canceled | Subscribe | AWS IoT publishes this message when a job is canceled. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/jobID/cancellation\$1in\$1progress | Subscribe | AWS IoT publishes this message when a job cancellation is in progress. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/*jobID*/completed | Subscribe | AWS IoT publishes this message when a job has completed. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/jobID/deleted | Subscribe | AWS IoT publishes this message when a job is deleted. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/jobID/deletion\$1in\$1progress | Subscribe | AWS IoT publishes this message when a job deletion is in progress. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/canceled | Subscribe | AWS IoT publishes this message when a job execution is canceled. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/deleted | Subscribe | AWS IoT publishes this message when a job execution is deleted. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/failed | Subscribe | AWS IoT publishes this message when a job execution has failed. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/rejected | Subscribe | AWS IoT publishes this message when a job execution was rejected. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/removed | Subscribe | AWS IoT publishes this message when a job execution was removed. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/succeeded | Subscribe | AWS IoT publishes this message when a job execution succeeded. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/jobID/timed\$1out | Subscribe | AWS IoT publishes this message when a job execution timed out. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/presence/connected/*clientId* | Subscribe | AWS IoT publishes to this topic when an MQTT client with the specified client ID connects to AWS IoT. For more information, see [Connect/Disconnect events](life-cycle-events.md#connect-disconnect). | | \$1aws/events/presence/disconnected/*clientId* | Subscribe | AWS IoT publishes to this topic when an MQTT client with the specified client ID disconnects to AWS IoT. For more information, see [Connect/Disconnect events](life-cycle-events.md#connect-disconnect). | | \$1aws/events/subscriptions/subscribed/*clientId* | Subscribe | AWS IoT publishes to this topic when an MQTT client with the specified client ID subscribes to an MQTT topic. For more information, see [Subscribe/Unsubscribe events](life-cycle-events.md#subscribe-unsubscribe-events). | | \$1aws/events/subscriptions/unsubscribed/*clientId* | Subscribe | AWS IoT publishes to this topic when an MQTT client with the specified client ID unsubscribes to an MQTT topic. For more information, see [Subscribe/Unsubscribe events](life-cycle-events.md#subscribe-unsubscribe-events). | | \$1aws/events/thing/*thingName*/created | Subscribe | AWS IoT publishes to this topic when the *thingName* thing is created. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thing/*thingName*/updated | Subscribe | AWS IoT publishes to this topic when the *thingName* thing is updated. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thing/*thingName*/deleted | Subscribe | AWS IoT publishes to this topic when the *thingName* thing is deleted. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroup/*thingGroupName*/created | Subscribe | AWS IoT publishes to this topic when thing group *thingGroupName* is created. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroup/*thingGroupName*/updated | Subscribe | AWS IoT publishes to this topic when thing group *thingGroupName* is updated. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroup/*thingGroupName*/deleted | Subscribe | AWS IoT publishes to this topic when thing group *thingGroupName* is deleted. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingType/*thingTypeName*/created | Subscribe | AWS IoT publishes to this topic when the *thingTypeName* thing type is created. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingType/*thingTypeName*/updated | Subscribe | AWS IoT publishes to this topic when the *thingTypeName* thing type is updated. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingType/*thingTypeName*/deleted | Subscribe | AWS IoT publishes to this topic when the *thingTypeName* thing type is deleted. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingTypeAssociation/thing/*thingName*/*thingTypeName* | Subscribe | AWS IoT publishes to this topic when thing *thingName* is associated with or disassociated from thing type *thingTypeName*. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroupMembership/thingGroup/*thingGroupName*/thing/*thingName*/added | Subscribe | AWS IoT publishes to this topic when thing *thingName* is added to thing group *thingGroupName*. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroupMembership/thingGroup/*thingGroupName*/thing/*thingName*/removed | Subscribe | AWS IoT publishes to this topic when thing *thingName* is removed from thing group *thingGroupName*. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroupHierarchy/thingGroup/*parentThingGroupName*/childThingGroup/*childThingGroupName*/added | Subscribe | AWS IoT publishes to this topic when thing group *childThingGroupName* is added to thing group *parentThingGroupName*. For more information, see [Registry events](registry-events.md). | | \$1aws/events/thingGroupHierarchy/thingGroup/*parentThingGroupName*/childThingGroup/*childThingGroupName*/removed | Subscribe | AWS IoT publishes to this topic when thing group *childThingGroupName* is removed from thing group *parentThingGroupName*. For more information, see [Registry events](registry-events.md). | ## Fleet provisioning topics **Note** The client operations noted as **Receive** in this table indicate topics that AWS IoT publishes directly to the client that requested it, whether the client has subscribed to the topic or not. Clients should expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules. These messages support response buffers in Concise Binary Object Representation (CBOR) format and JavaScript Object Notation (JSON), depending on the *payload-format* of the topic. | *payload-format* | Response format data type | | --- | --- | | cbor | Concise Binary Object Representation (CBOR) | | json | JavaScript Object Notation (JSON) | For more information, see [Device provisioning MQTT API](fleet-provision-api.md). | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/certificates/create/*payload-format* | Publish | Publish to this topic to create a certificate from a certificate signing request (CSR). | | \$1aws/certificates/create/*payload-format*/accepted | Subscribe, Receive | AWS IoT publishes to this topic after a successful call to \$1aws/certificates/create/*payload-format*. | | \$1aws/certificates/create/*payload-format*/rejected | Subscribe, Receive | AWS IoT publishes to this topic after an unsuccessful call to \$1aws/certificates/create/*payload-format*. | | \$1aws/certificates/create-from-csr/*payload-format* | Publish | Publishes to this topic to create a certificate from a CSR. | | \$1aws/certificates/create-from-csr/*payload-format*/accepted | Subscribe, Receive | AWS IoT publishes to this topic a successful call to \$1aws/certificates/create-from-csr/*payload-format*. | | \$1aws/certificates/create-from-csr/*payload-format*/rejected | Subscribe, Receive | AWS IoT publishes to this topic an unsuccessful call to \$1aws/certificates/create-from-csr/*payload-format*. | | \$1aws/provisioning-templates/*templateName*/provision/*payload-format* | Publish | Publish to this topic to register a thing. | | \$1aws/provisioning-templates/*templateName*/provision/*payload-format*/accepted | Subscribe, Receive | AWS IoT publishes to this topic after a successful call to \$1aws/provisioning-templates/*templateName*/provision/*payload-format*. | | \$1aws/provisioning-templates/*templateName*/provision/*payload-format*/rejected | Subscribe, Receive | AWS IoT publishes to this topic after an unsuccessful call to \$1aws/provisioning-templates/*templateName*/provision/*payload-format*. | ## Job topics **Note** The client operations noted as **Receive** in this table indicate topics that AWS IoT publishes directly to the client that requested it, whether the client has subscribed to the topic or not. Clients should expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules. To subscribe to job activity related messages, use the `notify` and `notify-next` topics. When subscribing to the job and `jobExecution` event topics for your fleet-monitoring solution, you must first enable [job and job execution events](iot-events.md) to receive any events on the cloud side. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/things/*thingName*/jobs/get | Publish | Devices publish a message to this topic to make a `GetPendingJobExecutions` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/get/accepted | Subscribe, Receive | Devices subscribe to this topic to receive successful responses from a `GetPendingJobExecutions` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/get/rejected | Subscribe, Receive | Devices subscribe to this topic to receive a response when a `GetPendingJobExecutions` request is rejected. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/start-next | Publish | Devices publish a message to this topic to make a `StartNextPendingJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/start-next/accepted | Subscribe, Receive | Devices subscribe to this topic to receive successful responses to a `StartNextPendingJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/start-next/rejected | Subscribe, Receive | Devices subscribe to this topic to receive a response when a `StartNextPendingJobExecution` request is rejected. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/*jobId*/get | Publish | Devices publish a message to this topic to make a `DescribeJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/*jobId*/get/accepted | Subscribe, Receive | Devices subscribe to this topic to receive successful responses to a `DescribeJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/*jobId*/get/rejected | Subscribe, Receive | Devices subscribe to this topic to receive a response when a `DescribeJobExecution` request is rejected. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/*jobId*/update | Publish | Devices publish a message to this topic to make an `UpdateJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/*jobId*/update/accepted | Subscribe, Receive | Devices subscribe to this topic to receive successful responses to an `UpdateJobExecution` request. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). Note Only the device that publishes to \$1aws/things/*thingName*/jobs/*jobId*/update receives messages on this topic. | | \$1aws/things/*thingName*/jobs/*jobId*/update/rejected | Subscribe, Receive | Devices subscribe to this topic to receive a response when an `UpdateJobExecution` request is rejected. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). Note Only the device that publishes to \$1aws/things/*thingName*/jobs/*jobId*/update receives messages on this topic. | | \$1aws/things/*thingName*/jobs/notify | Subscribe, Receive | Devices subscribe to this topic to receive notifications when a job execution is added or removed to the list of pending executions for a thing. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/things/*thingName*/jobs/notify-next | Subscribe, Receive | Devices subscribe to this topic to receive notifications when the next pending job execution for the thing is changed. For more information, see [Jobs device MQTT API operations](jobs-mqtt-api.md). | | \$1aws/events/job/*jobId*/completed | Subscribe | The Jobs service publishes an event on this topic when a job completes. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/*jobId*/canceled | Subscribe | The Jobs service publishes an event on this topic when a job is canceled. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/*jobId*/deleted | Subscribe | The Jobs service publishes an event on this topic when a job is deleted. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/*jobId*/cancellation\$1in\$1progress | Subscribe | The Jobs service publishes an event on this topic when a job cancellation begins. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/job/*jobId*/deletion\$1in\$1progress | Subscribe | The Jobs service publishes an event on this topic when a job deletion begins. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/succeeded | Subscribe | The Jobs service publishes an event on this topic when job execution succeeds. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/failed | Subscribe | The Jobs service publishes an event on this topic when a job execution fails. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/rejected | Subscribe | The Jobs service publishes an event on this topic when a job execution is rejected. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/canceled | Subscribe | The Jobs service publishes an event on this topic when a job execution is canceled. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/timed\$1out | Subscribe | The Jobs service publishes an event on this topic when a job execution times out. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/removed | Subscribe | The Jobs service publishes an event on this topic when a job execution is removed. For more information, see [Jobs events](events-jobs.md). | | \$1aws/events/jobExecution/*jobId*/deleted | Subscribe | The Jobs service publishes an event on this topic when a job execution is deleted. For more information, see [Jobs events](events-jobs.md). | ## Commands topics **Note** The client operations noted as **Receive** in this table indicate topics that AWS IoT publishes directly to the client that requested it, whether the client has subscribed to the topic or not. Clients should expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules. | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/commands/**/**/executions/**/request/** \$1aws/commands/**/**/executions/**/request | Subscribe, Receive | Devices receive a message on this topic when a request is made to start a command execution from the console or using the `StartCommandExecution` API. In this case, the ** can be either IoT things or MQTT clients, and ** can be either the IoT thing name or the MQTT client ID. | | \$1aws/commands/**/**/executions/**/response/** | Publish | Devices use the `UpdateCommandExecution` MQTT API to publish a message to this topic about the command execution. The message is published as a response to the request to start a command execution from the console or using the `StartCommandExecution` API. The published message will use JSON or CBOR as the **. | | \$1aws/commands/**/**/executions/**/response/accepted/** \$1aws/commands/**/**/executions/**/response/accepted | Subscribe, Receive | If the cloud service successfully processed the command execution result, AWS IoT Device Management publishes a response to the /accepted topic. | | \$1aws/commands/**/**/executions/**/response/rejected/** \$1aws/commands/**/**/executions/**/response/rejected | Publish | If the cloud service failed to process the command execution result, AWS IoT Device Management publishes a response to the /rejected topic. | ## Rule topics | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/rules/*ruleName* | Publish | A device or an application publishes to this topic to trigger rules directly. For more information, see [Reducing messaging costs with Basic Ingest](iot-basic-ingest.md). | ## Secure tunneling topics | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/things/*thing-name*/tunnels/notify | Subscribe | AWS IoT publishes this message for an IoT agent to start a local proxy on the remote device. For more information, see [IoT agent snippet](configure-remote-device.md#agent-snippet). | ## Shadow topics The topics in this section are used by named and unnamed shadows. The topics used by each differ only in the topic prefix. This table shows the topic prefix used by each shadow type. | *ShadowTopicPrefix* value | Shadow type | | --- | --- | | \$1aws/things/thingName/shadow | Unnamed (classic) shadow | | \$1aws/things/thingName/shadow/name/shadowName | Named shadow | To create a complete topic, select the *ShadowTopicPrefix* for the type of shadow to which you want to refer, replace *thingName* and if applicable, *shadowName*, with their corresponding values, and then append that with the topic stub as shown in the following table. Remember that topics are case sensitive. | Topic | Client operations allowed | Description | | --- | --- | --- | | *ShadowTopicPrefix*/delete | Publish/Subscribe | A device or an application publishes to this topic to delete a shadow. For more information, see [/delete](device-shadow-mqtt.md#delete-pub-sub-topic). | | *ShadowTopicPrefix*/delete/accepted | Subscribe | The Device Shadow service sends messages to this topic when a shadow is deleted. For more information, see [/delete/accepted](device-shadow-mqtt.md#delete-accepted-pub-sub-topic). | | *ShadowTopicPrefix*/delete/rejected | Subscribe | The Device Shadow service sends messages to this topic when a request to delete a shadow is rejected. For more information, see [/delete/rejected](device-shadow-mqtt.md#delete-rejected-pub-sub-topic). | | *ShadowTopicPrefix*/get | Publish/Subscribe | An application or a thing publishes an empty message to this topic to get a shadow. For more information, see [Device Shadow MQTT topics](device-shadow-mqtt.md). | | *ShadowTopicPrefix*/get/accepted | Subscribe | The Device Shadow service sends messages to this topic when a request for a shadow is made successfully. For more information, see [/get/accepted](device-shadow-mqtt.md#get-accepted-pub-sub-topic). | | *ShadowTopicPrefix*/get/rejected | Subscribe | The Device Shadow service sends messages to this topic when a request for a shadow is rejected. For more information, see [/get/rejected](device-shadow-mqtt.md#get-rejected-pub-sub-topic). | | *ShadowTopicPrefix*/update | Publish/Subscribe | A thing or application publishes to this topic to update a shadow. For more information, see [/update](device-shadow-mqtt.md#update-pub-sub-topic). | | *ShadowTopicPrefix*/update/accepted | Subscribe | The Device Shadow service sends messages to this topic when an update is successfully made to a shadow. For more information, see [/update/accepted](device-shadow-mqtt.md#update-accepted-pub-sub-topic). | | *ShadowTopicPrefix*/update/rejected | Subscribe | The Device Shadow service sends messages to this topic when an update to a shadow is rejected. For more information, see [/update/rejected](device-shadow-mqtt.md#update-rejected-pub-sub-topic). | | *ShadowTopicPrefix*/update/delta | Subscribe | The Device Shadow service sends messages to this topic when a difference is detected between the reported and desired sections of a shadow. For more information, see [/update/delta](device-shadow-mqtt.md#update-delta-pub-sub-topic). | | *ShadowTopicPrefix*/update/documents | Subscribe | AWS IoT publishes a state document to this topic whenever an update to the shadow is successfully performed. For more information, see [/update/documents](device-shadow-mqtt.md#update-documents-pub-sub-topic). | ## MQTT-based file delivery topics **Note** The client operations noted as **Receive** in this table indicate topics that AWS IoT publishes directly to the client that requested it, whether the client has subscribed to the topic or not. Clients should expect to receive these response messages even if they haven't subscribed to them. These response messages don't pass through the message broker and they can't be subscribed to by other clients or rules. These messages support response buffers in Concise Binary Object Representation (CBOR) format and JavaScript Object Notation (JSON), depending on the *payload-format* of the topic. | *payload-format* | Response format data type | | --- | --- | | cbor | Concise Binary Object Representation (CBOR) | | json | JavaScript Object Notation (JSON) | | Topic | Client operations allowed | Description | | --- | --- | --- | | \$1aws/things/*ThingName*/streams/*StreamId*/data/*payload-format* | Subscribe, Receive | AWS MQTT-based file delivery publishes to this topic if the "GetStream" request from a device is accepted. The payload contains the stream data. For more information, see [Using AWS IoT MQTT-based file delivery in devices](mqtt-based-file-delivery-in-devices.md). | | \$1aws/things/*ThingName*/streams/*StreamId*/get/*payload-format* | Publish | A device publishes to this topic to perform a "GetStream" request. For more information, see [Using AWS IoT MQTT-based file delivery in devices](mqtt-based-file-delivery-in-devices.md). | | \$1aws/things/*ThingName*/streams/*StreamId*/description/*payload-format* | Subscribe, Receive | AWS MQTT-based file delivery publishes to this topic if the "DescribeStream" request from a device is accepted. The payload contains the stream description. For more information, see [Using AWS IoT MQTT-based file delivery in devices](mqtt-based-file-delivery-in-devices.md). | | \$1aws/things/*ThingName*/streams/*StreamId*/describe/*payload-format* | Publish | A device publishes to this topic to perform a "DescribeStream" request. For more information, see [Using AWS IoT MQTT-based file delivery in devices](mqtt-based-file-delivery-in-devices.md). | | \$1aws/things/*ThingName*/streams/*StreamId*/rejected/*payload-format* | Subscribe, Receive | AWS MQTT-based file delivery publishes to this topic if a "DescribeStream" or "GetStream" request from a device is rejected. For more information, see [Using AWS IoT MQTT-based file delivery in devices](mqtt-based-file-delivery-in-devices.md). | ## Reserved topic ARN All reserved topic ARNs (Amazon Resource Names) have the following form: ``` arn:aws:iot:aws-region:AWS-account-ID:topic/Topic ``` For example, `arn:aws:iot:us-west-2:123EXAMPLE456:topic/$aws/things/thingName/jobs/get/accepted` is an ARN for the reserved topic `$aws/things/thingName/jobs/get/accepted`. # Domain configurations In AWS IoT Core, you can use domain configurations to configure and manage the behaviors of your data endpoints. With domain configurations, you can generate multiple AWS IoT Core data endpoints, customize them with your own fully qualified domain names (FQDN) and associated server certificates, and also associate a custom authorizer. For more information, see [Custom authentication and authorization](custom-authentication.md). **Note** This feature is not available in AWS GovCloud (US) AWS Regions. **Topics** + [ # What is a domain configuration? ](iot-domain-configuration-what-is.md) + [ # Creating and configuring AWS managed domains ](iot-custom-endpoints-configurable-aws.md) + [ # Creating and configuring customer managed domains ](iot-custom-endpoints-configurable-custom.md) + [ # Managing domain configurations ](iot-custom-endpoints-managing.md) + [ # Configuring TLS settings in domain configurations ](iot-endpoints-tls-config.md) + [ # Server certificate configuration for OCSP stapling ](iot-custom-endpoints-cert-config.md) # What is a domain configuration? In AWS IoT Core, a domain configuration refers to the setup and configuration of a domain (either AWS managed domain or customer managed domain) for your AWS IoT Core data endpoints. AWS IoT Core also provides a default endpoint for your AWS account (`iot:Data-ATS`) for devices to communicate with AWS IoT Core. **Topics** + [ ## Use cases ](#iot-custom-endpoints-configurable-use-cases) + [ ## Key concepts ](#iot-domain-configuration-key-concepts) + [ ## Important notes ](#iot-custom-endpoints-configurable-notes) ## Use cases You can use domain configurations to simplify tasks like the following. + Migrate devices to AWS IoT Core. + Support heterogeneous device fleets by maintaining separate domain configurations for separate device types. + Maintain brand identity (for example, through domain name) while migrating application infrastructure to AWS IoT Core. ## Key concepts The following concepts provide details about domain configurations and related concepts. + **Domain configuration** The setup and configuration of a domain for your AWS IoT Core endpoints. + **Default endpoint domain** The domain that AWS IoT provides with the default endpoint such as `iot:Data-ATS`. To find the default endpoint, run the [describe-endpoint](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-endpoint.html) or [describe-domain-configuration](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-domain-configuration.html) CLI command. Alternatively, go to AWS IoT Core console, choose **Domain configurations** from **Connect** on the left navigation. The default endpoint is listed with the name `iot:Data-ATS`. + **AWS managed domain** The domain that AWS will manage. Choosing AWS managed domain means that your devices will connect using a data endpoint provided by AWS. AWS will manage the domain and the certificates. + **Customer managed domain** The domain that you will manage. Also known as custom domain. Choosing customer managed domain means that your devices will connect using a custom domain data endpoint. You will manage the domain and the certificates. Customer managed domain allows you to tailor the endpoint URLs to suit your needs. For example, you can use a custom domain name (`your-domain-name.com`) or apply specific access policies. + **Authentication type** The authentication type that you choose to authenticate your devices when connecting to AWS IoT Core. When creating a domain configuration, you must specify an authentication type. For more information, see [Choosing an authentication type for your device communication](protocols.md#connection-protocol-auth-mode). + **Application protocol** The application layer protocols which your devices use when connecting to AWS IoT Core. When creating a domain configuration, you must specify an application protocol. For more information, see [Choosing an application protocol for your device communication](protocols.md#protocol-selection). ## Important notes AWS IoT Core uses the [server name indication (SNI) TLS extension](https://www.rfc-editor.org/rfc/rfc3546) to apply domain configurations. When connecting devices to AWS IoT Core, clients can send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1), which is required for features such as [multi-account registration](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html#multiple-account-cert), [configurable endpoints](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable.html), [custom domains](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable-custom.html), and [VPC endpoints](https://docs.aws.amazon.com//iot/latest/developerguide/IoTCore-VPC.html). They also must pass a server name that is identical to the domain name that you specify in the domain configuration. To test this service, use the v2 version of the [AWS IoT Device SDKs](https://github.com/aws) in GitHub. If you create multiple data endpoints in your AWS account, they will share AWS IoT Core resources such as MQTT topics, device shadows, and rules. When you provide the server certificates for AWS IoT Core custom domain configuration, the certificates have a maximum of four domain names. For more information, see [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#security-limits). # Creating and configuring AWS managed domains You create a configurable endpoint on an AWS managed domain by using the [CreateDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateDomainConfiguration.html) API. A domain configuration for an AWS managed domain consists of the following: + `domainConfigurationName` A user-defined name that identifies the domain configuration and the value must be unique to your AWS Region. You can't use domain configuration names that start with `IoT:` because they are reserved for default endpoints. + `defaultAuthorizerName` (optional) The name of the custom authorizer to use on the endpoint. + `allowAuthorizerOverride` (optional) A Boolean value that specifies whether devices can override the default authorizer by specifying a different authorizer in the HTTP header of the request. This value is required if a value for `defaultAuthorizerName` is specified. + `serviceType` (optional) The service type that the endpoint delivers. AWS IoT Core only supports the `DATA` service type. When you specify `DATA`, AWS IoT Core returns an endpoint with an endpoint type of `iot:Data-ATS`. You can't create a configurable `iot:Data` (VeriSign) endpoint. + `TlsConfig` (optional) An object that specifies the TLS configuration for a domain. For more information, see [Configuring TLS settings in domain configurations](iot-endpoints-tls-config.md). The following example AWS CLI command creates a domain configuration for a `Data` endpoint. ``` aws iot create-domain-configuration --domain-configuration-name "myDomainConfigurationName" --service-type "DATA" ``` The output of the command can look like the following. ``` { "domainConfigurationName": "myDomainConfigurationName", "domainConfigurationArn": "arn:aws:iot:us-east-1:123456789012:domainconfiguration/myDomainConfigurationName/itihw" } ``` # Creating and configuring customer managed domains Domain configurations let you specify a custom fully qualified domain name (FQDN) to connect to AWS IoT Core. There are many benefits of using customer managed domains (also known as custom domains): you can expose your own domain or your company's own domain to customers for branding purposes; you can easily change your own domain to point to a new broker; you can support multi-tenancy to serve customers with different domains within the same AWS account; and you can manage your own server certificates details, such as the root certificate authority (CA) used to sign the certificate, the signature algorithm, the certificate chain depth, and the lifecycle of the certificate. The workflow to set up a domain configuration with a custom domain consists of the following three stages. 1. [Registering Server Certificates in AWS Certificate Manager](#iot-custom-endpoints-configurable-custom-register-certificate) 1. [Creating a Domain Configuration](#iot-custom-endpoints-configurable-custom-domain-config) 1. [Creating DNS Records](#iot-custom-endpoints-configurable-custom-dns) ## Registering server certificates in AWS certificate manager Before you create a domain configuration with a custom domain, you must register your server certificate chain in [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html). You can use the following three types of server certificates. + [ACM Generated Public Certificates](#iot-custom-endpoints-configurable-custom-register-certificate-acm) + [External Certificates Signed by a Public CA](#iot-custom-endpoints-configurable-custom-register-certificate-pubext) + [External Certificates Signed by a Private CA](#iot-custom-endpoints-configurable-custom-register-certificate-privext) **Note** AWS IoT Core considers a certificate to be signed by a public CA if it's included in [Mozilla's trusted ca-bundle](https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt?raw=1). ### Certificate requirements See [Prerequisites for Importing Certificates](/acm/latest/userguide/import-certificate-prerequisites.html) for the requirements for importing certificates into ACM. In addition to these requirements, AWS IoT Core adds the following requirements. + The leaf certificate must include the **Extended Key Usage** x509 v3 extension with a value of **serverAuth** (TLS Web Server Authentication). If you request the certificate from ACM, this extension is automatically added. + The maximum certificate chain depth is 5 certificates. + The maximum certificate chain size is 16KB. + The cryptographic algorithms and key sizes that are supported include RSA 2048 bit (RSA\$12048) and ECDSA 256 bit (EC\$1prime256v1). ### Using one certificate for multiple domains If you plan to use one certificate to cover multiple subdomains, use a wildcard domain in the common name (CN) or Subject Alternative Names (SAN) field. For example, use **\$1.iot.example.com** to cover dev.iot.example.com, qa.iot.example.com, and prod.iot.example.com. Each FQDN requires its own domain configuration, but more than one domain configuration can use the same wildcard value. Either the CN or the SAN must cover the FQDN that you want to use as a custom domain. If SANs are present, the CN is ignored and a SAN must cover the FQDN that you want to use as a custom domain. This coverage can be an exact match or a wildcard match. After a wildcard certificate has been validated and registered to an account, other accounts in the region are blocked from creating custom domains that overlap with the certificate. The following sections describe how to get each type of certificate. Every certificate resource requires an Amazon Resource Name (ARN) registered with ACM that you use when you create your domain configuration. ### ACM-generated public certificates You can generate a public certificate for your custom domain by using the [RequestCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_RequestCertificate.html) API. When you generate a certificate in this way, ACM validates your ownership of the custom domain. For more information, see [Request a Public Certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) in the *AWS Certificate Manager User Guide*. ### External certificates signed by a public CA If you already have a server certificate that is signed by a public CA (a CA that is included in Mozilla's trusted ca-bundle), you can import the certificate chain directly into ACM by using the [ImportCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_ImportCertificate.html) API. To learn more about this task and the prerequisites and certificate format requirements, see [Importing Certificates](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html). ### External certificates signed by a private CA If you already have a server certificate that is signed by a private CA or self-signed, you can use the certificate to create your domain configuration, but you also must create an extra public certificate in ACM to validate ownership of your domain. To do this, register your server certificate chain in ACM using the [ImportCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_ImportCertificate.html) API. To learn more about this task and the prerequisites and certificate format requirements, see [Importing Certificates](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html). ### Creating a validation certificate After you import your certificate to ACM, generate a public certificate for your custom domain by using the [RequestCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_RequestCertificate.html) API. When you generate a certificate in this way, ACM validates your ownership of the custom domain. For more information, see [Request a Public Certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html). When you create your domain configuration, use this public certificate as your validation certificate. ## Creating a domain configuration You create a configurable endpoint on a custom domain by using the [CreateDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateDomainConfiguration.html) API. A domain configuration for a custom domain consists of the following: + `domainConfigurationName` A user-defined name that identifies the domain configuration. Domain configuration names starting with `IoT:` are reserved for default endpoints and can't be used. Also, this value must be unique to your AWS Region. + `domainName` The FQDN that your devices use to connect to AWS IoT Core. AWS IoT Core leverages the server name indication (SNI) TLS extension to apply domain configurations. Devices must use this extension when connecting and pass a server name that is identical to the domain name that is specified in the domain configuration. + `serverCertificateArns` The ARN of the server certificate chain that you registered with ACM. AWS IoT Core currently supports only one server certificate. + `validationCertificateArn` The ARN of the public certificate that you generated in ACM to validate ownership of your custom domain. This argument isn't required if you use a publicly signed or ACM-generated server certificate. + `defaultAuthorizerName (optional)` The name of the custom authorizer to use on the endpoint. + `allowAuthorizerOverride` A Boolean value that specifies whether devices can override the default authorizer by specifying a different authorizer in the HTTP header of the request. This value is required if a value for `defaultAuthorizerName` is specified. + `serviceType` AWS IoT Core currently supports only the `DATA` service type. When you specify `DATA`, AWS IoT returns an endpoint with an endpoint type of `iot:Data-ATS`. + `TlsConfig` (optional) An object that specifies the TLS configuration for a domain. For more information, see [Configuring TLS settings in domain configurations](iot-endpoints-tls-config.md). + `serverCertificateConfig` (optional) An object that specifies the server certificate configuration for a domain. For more information, see [Server certificate configuration for OCSP stapling](iot-custom-endpoints-cert-config.md). The following AWS CLI command creates a domain configuration for **iot.example.com**. ``` aws iot create-domain-configuration --domain-configuration-name "myDomainConfigurationName" --service-type "DATA" --domain-name "iot.example.com" --server-certificate-arns serverCertARN --validation-certificate-arn validationCertArn ``` **Note** After you create your domain configuration, it might take up to 60 minutes until AWS IoT Core serves your custom server certificates. For more information, see [Managing domain configurations](iot-custom-endpoints-managing.md). ## Creating DNS records After you register your server certificate chain and create your domain configuration, create a DNS record so that your custom domain points to an AWS IoT domain. This record must point to an AWS IoT endpoint of type `iot:Data-ATS`. You can get your endpoint by using the [DescribeEndpoint](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEndpoint.html) API. The following AWS CLI command shows how to get your endpoint. ``` aws iot describe-endpoint --endpoint-type iot:Data-ATS ``` After you get your `iot:Data-ATS` endpoint, create a `CNAME` record from your custom domain to this AWS IoT endpoint. If you create multiple custom domains in the same AWS account, alias them to this same `iot:Data-ATS` endpoint. ## Troubleshooting If you have trouble connecting devices to a custom domain, make sure that AWS IoT Core has accepted and applied your server certificate. You can verify that AWS IoT Core has accepted your certificate by using either the AWS IoT Core console or the AWS CLI. To use the AWS IoT Core console, navigate to the **Domain configurations** page and select the domain configuration name. In the **Server certificate details** section, check the status and status details. If the certificate is invalid, replace it in ACM with a certificate that meets the [certificate requirements](#certificate-requirements) listed in the previous section. If the certificate has the same ARN, AWS IoT Core will be pick it up and apply it automatically. To check the certificate status by using the AWS CLI, call the [DescribeDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeDomainConfiguration.html) API and specify your domain configuration name. **Note** If your certificate is invalid, AWS IoT Core will continue to serve the last valid certificate. You can check which certificate is being served on your endpoint by using the following openssl command. `openssl s_client -connect custom-domain-name:8883 -showcerts -servername custom-domain-name` # Managing domain configurations This topic covers key operations for you to manage your domain configuration resources. You can also manage the lifecycles of existing configurations by using the following APIs: [ListDomainConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_ListDomainConfigurations.html), [DescribeDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeDomainConfiguration.html), [UpdateDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateDomainConfiguration.html), and [DeleteDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteDomainConfiguration.html). **Topics** + [ ## Viewing domain configurations ](#iot-custom-endpoints-managing-view) + [ ## Updating domain configurations ](#iot-custom-endpoints-managing-update) + [ ## Deleting domain configurations ](#iot-custom-endpoints-managing-delete) + [ ## Rotating certificates in custom domains ](#iot-custom-endpoints-managing-certificates) ## Viewing domain configurations To return a paginated list of all domain configurations in your AWS account, use the [ListDomainConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_ListDomainConfigurations.html) API . You can see the details of a particular domain configuration using the [DescribeDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeDomainConfiguration.html) API. This API takes a single `domainConfigurationName` parameter and returns the details of the specified configuration. **Example** ## Updating domain configurations To update the status or the custom authorizer of your domain configuration, use the [UpdateDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateDomainConfiguration.html) API. You can set the status to `ENABLED` or `DISABLED`. If you disable the domain configuration, devices connected to that domain receive an authentication error. Currently you can't update the server certificate in your domain configuration. To change the certificate of a domain configuration, you must delete and recreate it. **Example** ## Deleting domain configurations Before you delete a domain configuration, use the [UpdateDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateDomainConfiguration.html) API to set the status to `DISABLED`. This helps you avoid accidentally deleting the endpoint. After you disable the domain configuration, delete it by using the [DeleteDomainConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteDomainConfiguration.html) API. You must place AWS-managed domains in `DISABLED` status for 7 days before you can delete them. You can place custom domains in `DISABLED` status and then delete them at once. **Example** After you delete a domain configuration, AWS IoT Core no longer serves the server certificate associated with that custom domain. ## Rotating certificates in custom domains You may need to periodically replace your server certificate with an updated certificate. The rate at which you do this depends on the validity period of your certificate. If you generated your server certificate by using AWS Certificate Manager (ACM), you can set the certificate to renew automatically. When ACM renews your certificate, AWS IoT Core automatically picks up the new certificate. You don't have to perform any additional action. If you imported your server certificate from a different source, you can rotate it by reimporting it to ACM. For information about reimporting certificates, see [Reimport a certificate](https://docs.aws.amazon.com/acm/latest/userguide/import-reimport.html). **Note** AWS IoT Core only picks up certificate updates under the following conditions. The new certificate has the same ARN as the old one. The new certificate has the same signing algorithm, common name, or subject alternative name as the old one. # Configuring TLS settings in domain configurations AWS IoT Core provides [predefined security polices](transport-security.md#tls-policy-table) for you to customize your Transport Layer Security (TLS) settings for [TLS 1.2](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2) and [TLS 1.3](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.3) in domain configurations. A security policy is a combination of TLS protocols and their ciphers that determine the supported protocols and ciphers during TLS negotiations between a client and a server. With the supported security policies, you can manage your devices' TLS settings with more flexibility, apply the most up-to-date security measures when connecting new devices, and maintain consistent TLS configurations for existing devices. The following table describes the security policies, their TLS versions, and supported regions: **** | Security policy name | Supported AWS Regions | | --- | --- | | IoTSecurityPolicy\$1TLS13\$11\$13\$12022\$110 | All AWS Regions | | IoTSecurityPolicy\$1TLS13\$11\$12\$12022\$110 | All AWS Regions | | IoTSecurityPolicy\$1TLS12\$11\$12\$12022\$110 | All AWS Regions | | IoTSecurityPolicy\$1TLS12\$11\$10\$12016\$101 | ap-east-1, ap-northeast-2, ap-south-1, ap-southeast-2, ca-central-1, cn-north-1, cn-northwest-1, eu-north-1, eu-west-2, eu-west-3, me-south-1, sa-east-1, us-east-2, us-west-1 | | IoTSecurityPolicy\$1TLS12\$11\$10\$12015\$101 | ap-northeast-1, ap-southeast-1, eu-central-1, eu-west-1, us-east-1, us-west-2 | The names of the security policies in AWS IoT Core include version information based on the year and month that they were released. If you create a new domain configuration, the security policy will default to `IoTSecurityPolicy_TLS13_1_2_2022_10`. For a complete table of security policies with details of protocols, TCP ports, and ciphers, see [Security polices](transport-security.md#tls-policy-table). AWS IoT Core doesn't support custom security policies. For more information, see [Transport security in AWS IoT Core](transport-security.md). To configure TLS settings in domain configurations, you can use the AWS IoT console or the AWS CLI. **Topics** + [ ## Configure TLS settings in domain configurations (console) ](#custom-tls-console) + [ ## Configure TLS settings in domain configurations (CLI) ](#custom-tls-cli) ## Configure TLS settings in domain configurations (console) **To configure TLS settings using the AWS IoT console** 1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home). 1. To configure TLS settings when you create a new domain configuration, follow these steps. 1. In the left navigation pane, choose **Domain configurations**, and then choose **Create domain configuration**. 1. In the **Create domain configuration** page, in the **Custom domain settings - *optional*** section, choose a security policy from **Select security policy**. 1. Follow the widget and complete the rest of the steps. Choose **Create domain configuration**. 1. To update TLS settings in an existing domain configuration, follow these steps. 1. In the left navigation pane, choose **Domain configurations**, and then choose a domain configuration. 1. In the **Domain configuration details** page, choose **Edit**. Then, in the **Custom domain settings - *optional*** section, under **Select security policy**, choose a security policy. 1. Choose **Update domain configuration**. For more information, see [Create a domain configuration](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable-custom.html#iot-custom-endpoints-configurable-custom-domain-config) and [Manage domain configurations](iot-custom-endpoints-managing.md). ## Configure TLS settings in domain configurations (CLI) You can use the [https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html) and [https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html) CLI commands to configure your TLS settings in domain configurations. 1. To specify TLS settings using the [https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html) CLI command: ``` aws iot create-domain-configuration \ --domain-configuration-name domainConfigurationName \ --tls-config securityPolicy=IoTSecurityPolicy_TLS13_1_2_2022_10 ``` The output of this command can look like the following: ``` { "domainConfigurationName": "test", "domainConfigurationArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/test/34ga9" } ``` If you create a new domain configuration without specifying the security policy, the value will default to: `IoTSecurityPolicy_TLS13_1_2_2022_10`. 1. To describe TLS settings using the [https://docs.aws.amazon.com//cli/latest/reference/iot/describe-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-domain-configuration.html) CLI command: ``` aws iot describe-domain-configuration \ --domain-configuration-name domainConfigurationName ``` This command can return the domain configuration details that include the TLS settings like the following: ``` { "tlsConfig": { "securityPolicy": "IoTSecurityPolicy_TLS13_1_2_2022_10" }, "domainConfigurationStatus": "ENABLED", "serviceType": "DATA", "domainType": "AWS_MANAGED", "domainName": "d1234567890abcdefghij-ats.iot.us-west-2.amazonaws.com", "serverCertificates": [], "lastStatusChangeDate": 1678750928.997, "domainConfigurationName": "test", "domainConfigurationArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/test/34ga9" } ``` 1. To update TLS settings using the [https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html) CLI command: ``` aws iot update-domain-configuration \ --domain-configuration-name domainConfigurationName \ --tls-config securityPolicy=IoTSecurityPolicy_TLS13_1_2_2022_10 ``` The output of this command can look like the following: ``` { "domainConfigurationName": "test", "domainConfigurationArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/test/34ga9" } ``` 1. To update the TLS settings for your ATS endpoint, run the [https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html) CLI command. The domain configuration name for your ATS endpoint is `iot:Data-ATS`. ``` aws iot update-domain-configuration \ --domain-configuration-name "iot:Data-ATS" \ --tls-config securityPolicy=IoTSecurityPolicy_TLS13_1_2_2022_10 ``` The output of the command can look like the following: ``` { "domainConfigurationName": "iot:Data-ATS", "domainConfigurationArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/iot:Data-ATS" } ``` For more information, see [CreateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateDomainConfiguration.html) and [UpdateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_UpdateDomainConfiguration.html) in the *AWS API Reference*. # Server certificate configuration for OCSP stapling AWS IoT Core supports [Online Certificate Status Protocol (OCSP)](https://www.rfc-editor.org/rfc/rfc6960.html) stapling for server certificate, also known as server certificate OCSP stapling, or OCSP stapling. It is a security mechanism used to check the revocation status on the server certificate in a Transport Layer Security (TLS) handshake. OCSP stapling in AWS IoT Core lets you add an additional layer of verification to your custom domain's server certificate validity. You can enable server certificate OCSP stapling in AWS IoT Core to check the validity of the certificate by querying the OCSP responder periodically. The OCSP stapling setting is part of the process to create or update a domain configuration with a custom domain. OCSP stapling checks for revocation status on the server certificate continuously. This helps verify that any certificates that have been revoked by the CA are no longer trusted by the clients connecting to your custom domains. For more information, see [Enabling server certificate OCSP in AWS IoT Core](#iot-custom-endpoints-cert-config-ocsp-manage). Server certificate OCSP stapling provides real-time revocation status check, reduces the latency associated with checking the revocation status, and improves privacy and reliability of secure connections. For more information about the benefits of using OCSP stapling, see [Benefits of using OCSP stapling compared to client-side OCSP checks](#iot-custom-endpoints-ocsp-stapling-benefits). **Note** This feature is not available in AWS GovCloud (US) Regions. **Topics** + [ ## What is OCSP? ](#iot-custom-endpoints-cert-config-ocsp-what-is) + [ ## How OCSP stapling works ](#iot-custom-endpoints-cert-config-ocsp-stapling-what-is) + [ ## Enabling server certificate OCSP in AWS IoT Core ](#iot-custom-endpoints-cert-config-ocsp-manage) + [ ## Configuring server certificate OCSP for private endpoints in AWS IoT Core ](#iot-custom-endpoints-cert-config-ocsp-private-endpoint) + [ ## Important notes for using server certificate OCSP stapling in AWS IoT Core ](#iot-custom-endpoints-cert-config-ocsp-notes) + [ ## Troubleshooting server certificate OCSP stapling in AWS IoT Core ](#iot-custom-endpoints-cert-config-ocsp-troubleshooting) ## What is OCSP? The Online Certificate Status Protocol (OCSP) aids in providing a server certificate's revocation status for a Transport Layer Security (TLS) handshake. ### Key concepts The following key concepts provide details about the Online Certificate Status Protocol (OCSP). **OCSP** [OCSP](https://www.rfc-editor.org/rfc/rfc6960.html) is used to check the certificate revocation status during the Transport Layer Security (TLS) handshake. OCSP allows for real-time validation of certificates. This confirms that the certificate hasn't been revoked or expired since it was issued. OCSP is also more scalable compared with traditional Certificate Revocation Lists (CRLs). OCSP responses are smaller and can be efficiently generated, making them more suitable for large-scale Private Key Infrastructures (PKIs). **OCSP responder** An OCSP responder (also known as OCSP server) receives and responds to OCSP requests from clients that seek to verify the revocation status of certificates. **Client-side OCSP** In client-side OCSP, the client uses OCSP to contact an OCSP responder to check the certificate's revocation status during the TLS handshake. **Server-side OCSP** In server-side OCSP (also known as OCSP stapling), the server is enabled (rather than the client) to make the request to the OCSP responder. The server staples the OCSP response to the certificate and returns it to the client during the TLS handshake. ### OCSP diagrams The following diagram illustrates how client-side OCSP and server-side OCSP work. ![\[Client-side OCSP and server-side OCSP diagrams\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/custom-domain-ocsp-uml.png) **Client-side OCSP** 1. The client sends a `ClientHello` message to initiate the TLS handshake with the server. 1. The server receives the message and responds with a `ServerHello` message. The server also sends the server certificate to the client. 1. The client validates the server certificate and extracts an OCSP URI from it. 1. The client sends a certificate revocation check request to the OCSP responder. 1. The OCSP responder sends an OCSP response. 1. The client validates the certificate status from the OCSP response. 1. The TLS handshake is completed. **Server-side OCSP** 1. The client sends a `ClientHello` message to initiate the TLS handshake with the server. 1. The server receives the message and gets the latest cached OCSP response. If the cached response is missing or expired, the server will call the OCSP responder for certificate status. 1. The OCSP responder sends an OCSP response to the server. 1. The server sends a `ServerHello` message. The server also sends the server certificate and the certificate status to the client. 1. The client validates the OCSP certificate status. 1. The TLS handshake is completed. ## How OCSP stapling works OCSP stapling is used during the TLS handshake between the client and the server to check the server certificate revocation status. The server makes the OCSP request to the OCSP responder and staples the OCSP responses to the certificates returned to the client. By having the server make the request to the OCSP responder, the responses can be cached and then used multiple times for many clients. ### How OCSP stapling works in AWS IoT Core The following diagram shows how server-side OCSP stapling works in AWS IoT Core. ![\[This diagram shows how server-side OCSP stapling works in AWS IoT Core.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/custom-domain-ocsp-core-uml.png) 1. The device needs to be registered with custom domains with OCSP stapling enabled. 1. AWS IoT Core calls OCSP responder every hour to get the certificate status. 1. The OCSP responder receives the request, sends the latest OCSP response, and stores the cached OCSP response. 1. The device sends a `ClientHello` message to initiate the TLS handshake with AWS IoT Core. 1. AWS IoT Core gets the latest OCSP response from the server cache, which responds with an OCSP response of the certificate. 1. The server sends a `ServerHello` message to the device. The server also sends the server certificate and the certificate status to the client. 1. The device validates the OCSP certificate status. 1. The TLS handshake is completed. ### Benefits of using OCSP stapling compared to client-side OCSP checks A few advantages of using server certificate OCSP stapling include the following: **Improved privacy** Without OCSP stapling, the client's device can expose information to third-party OCSP responders, potentially compromising user privacy. OCSP stapling mitigates this issue by having the server obtain the OCSP response and deliver it directly to the client. **Improved reliability** OCSP stapling can improve the reliability of secure connections because it reduces the risk of OCSP server outages. When OCSP responses are stapled, the server includes the most recent response with the certificate. This is so that clients have access to the revocation status even if the OCSP responder is temporarily unavailable. OCSP stapling helps mitigate these problems because the server fetches OCSP responses periodically and includes the cached responses in the TLS handshake. This reduces reliance on the real-time availability of OCSP responders. **Reduced server load** OCSP stapling offloads the burden of responding to OCSP requests from OCSP responders to the server. This can help distribute the load more evenly, making the certificate validation process more efficient and scalable. **Reduced latency** OCSP stapling reduces the latency associated with checking the revocation status of a certificate during the TLS handshake. Instead of the client having to query an OCSP server separately, the server sends the request and attaches the OCSP response with the server certificate during the handshake. ## Enabling server certificate OCSP in AWS IoT Core To enable server certificate OCSP stapling in AWS IoT Core, create a domain configuration for a custom domain or update an existing custom domain configuration. For general information about creating a domain configuration with a custom domain, see [Creating and configuring customer managed domains](iot-custom-endpoints-configurable-custom.md). Use the following instructions to enable OCSP server stapling using AWS Management Console or AWS CLI. ### Console **To enable server certificate OCSP stapling using the AWS IoT console:** 1. In the navigation menu, choose **Settings**, and then choose **Create domain configuration**, or choose an existing domain configuration for a custom domain. 1. If you choose to create a new domain configuration in the previous step, you will see the **Create domain configuration** page. In the **Domain configuration properties** section, choose **Custom domain**. Enter the information to create a domain configuration. If you choose to update an existing domain configuration for a custom domain, you will see the **Domain configuration details** page. Choose **Edit**. 1. To enable OCSP server stapling, choose **Enable server certificate OCSP stapling** in the **Server certificate configurations** subsection. 1. Choose **Create domain configuration** or **Update domain configuration**. ### AWS CLI **To enable server certificate OCSP stapling using AWS CLI:** 1. If you create a new domain configuration for a custom domain, the command to enable the OCSP server stapling can look like the following: ``` aws iot create-domain-configuration --domain-configuration-name "myDomainConfigurationName" \ --server-certificate-arns arn:aws:iot:us-east-1:123456789012:cert/f8c1e5480266caef0fdb1bf97dc1c82d7ba2d3e2642c5f25f5ba364fc6b79ba3 \ --server-certificate-config "enableOCSPCheck=true|false" ``` 1. If you update an existing domain configuration for a custom domain, the command to enable the OCSP server stapling can look like the following: ``` aws iot update-domain-configuration --domain-configuration-name "myDomainConfigurationName" \ --server-certificate-arns arn:aws:iot:us-east-1:123456789012:cert/f8c1e5480266caef0fdb1bf97dc1c82d7ba2d3e2642c5f25f5ba364fc6b79ba3 \ --server-certificate-config "enableOCSPCheck=true|false" ``` For more information, see [CreateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateDomainConfiguration.html) and [UpdateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_UpdateDomainConfiguration.html) from the AWS IoT API Reference. ## Configuring server certificate OCSP for private endpoints in AWS IoT Core OCSP for private endpoints lets you use your private OCSP resources within your Amazon Virtual Private Cloud (Amazon VPC) for AWS IoT Core operations. The process involves setting up a Lambda function that acts as an OCSP responder. The Lambda function might use your private OCSP resources to craft OCSP responses that AWS IoT Core will use. ### Lambda function Before you configure server OCSP for a private endpoint, create a Lambda function that acts as a Request for Comments (RFC) 6960-compliant Online Certificate Status Protocol (OCSP) responder, supporting basic OCSP responses. The Lambda function accepts a base64-encoding of the OCSP request in the Distinguished Encoding Rules (DER) format. The Lambda function's response is also a base64-encoded OCSP response in the DER format. The response size must not exceed 4 kilobytes (KiB). The Lambda function must be in the same AWS account and AWS Region as the domain configuration. The following are example Lambda functions. #### Example Lambda functions ------ #### [ JavaScript ] ``` import * as pkijs from 'pkijs'; console.log('Loading function'); export const handler = async (event, context) => { const requestBytes = decodeBase64(event); const ocspRequest = pkijs.OCSPRequest.fromBER(requestBytes); console.log("Here is a better look at the OCSP request"); console.log(ocspRequest.toJSON()); const ocspResponse = getOcspResponse(); console.log("Here is a better look at the OCSP response"); console.log(ocspResponse.toJSON()); const responseBytes = ocspResponse.toSchema().toBER(); return encodeBase64(responseBytes); }; function getOcspResponse() { const responseString = "MIIC/woBAKCCAvgwggL0BgkrBgEFBQcwAQEEggLlMIIC4TCByqFkMGIxJzAlBgNVBAoMHlJpY2hhcmQncyBEaXNjb3VudCBMYW1iZGEgT0NTUDEZMBcGA1UEAwwQcm91bmRhYm91dE5hdGlvbjEPMA0GA1UEBwwGQ2FybWVsMQswCQYDVQQGEwJJThgPMjAyNDA0MjMxODUzMjVaMFEwTzA6MAkGBSsOAwIaBQAEFD2L7Ol/6ieNMaJbwRbxFWFweXGPBBSzSThwzTc3/p5w7WOtPjp3otNtVgIBAYAAGA8yMDI0MDQyMzE4NTMyNVowDQYJKoZIhvcNAQELBQADggIBAJFRyjDAHfazNejo704Ra3FOsGq/+s82R1spDarr3k7Pzkod9jJhwsZ2YgushlS4Npfe4lHCdwFyZR75WXrW55aXFddy03KLz01ZLNYyxkleW3f5dgrUcRU3PMW9TU2gZ0VOV8L5pmxKBoBRFt6EKtyh4CbiuqkTpLdLIMZmTyanhl5GVyU5MBHdbH8YWZoT/DEBiyS7ZsyhKo6igWU/SY7YMSKgwBvFsqSDcOa/hRYQkxWKWJ19gcz8CIkWN7NvfIxCs6VrAdzEJwmE7y3v+jdfhxW9JmI4xStE4K0tAR9vVOOfKs7NvxXj7oc9pCSG60xl96kaEE6PaY1YsfNTsKQ7pyCJ0s7/2q+ieZ4AtNyzw1XBadPzPJNv6E0LvI24yQZqN5wACvtut5prMMRxAHbOy+abLZR58wloFSELtGJ7UD96LFv1GgtC5s+2QlzPc4bEEof7Lo1EISt3j2ibNch8LxhqTQ4ufrbhsMkpSOTFYEJVMJF6aKj/OGXBUUqgc0Jx6jjJXNQd+l5KCY9pQFeb/wVUYC6mYqZOkNNMMJxPbHHbFnqb68yO+g5BE9011N44YXoPVJYoXxBLFX+OpRu9cqPkT9/vlkKd+SYXQknwZ81agKzhf1HsBKabtJwNVMlBKaI8g5UGa7Bxi6ewH3ezdWiERRUK7F56OM53wto/"; const responseBytes = decodeBase64(responseString); return pkijs.OCSPResponse.fromBER(responseBytes); } function decodeBase64(input) { const binaryString = atob(input); const byteArray = new Uint8Array(binaryString.length); for (var i = 0; i < binaryString.length; i++) { byteArray[i] = binaryString.charCodeAt(i); } return byteArray.buffer; } function encodeBase64(buffer) { var binary = ''; const bytes = new Uint8Array( buffer ); const len = bytes.byteLength; for (var i = 0; i < len; i++) { binary += String.fromCharCode( bytes[ i ] ); } return btoa(binary); } ``` ------ #### [ Java ] ``` package com.example.ocsp.responder; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.LambdaLogger; import com.amazonaws.services.lambda.runtime.RequestHandler; import org.bouncycastle.cert.ocsp.OCSPReq; import org.bouncycastle.cert.ocsp.OCSPResp; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Base64; public class LambdaResponderApplication implements RequestHandler { @Override public String handleRequest(final String input, final Context context) { LambdaLogger logger = context.getLogger(); byte[] decodedInput = Base64.getDecoder().decode(input); OCSPReq req; try { req = new OCSPReq(decodedInput); } catch (IOException e) { logger.log("Got an IOException creating the OCSP request: " + e.getMessage()); throw new RuntimeException(e); } try { OCSPResp response = businessLogic.getMyResponse(); String toReturn = Base64.getEncoder().encodeToString(response.getEncoded()); return toReturn; } catch (Exception e) { logger.log("Got an exception creating the response: " + e.getMessage()); return ""; } } } ``` ------ #### Authorizing AWS IoT to invoke your Lambda function In the process of creating the domain configuration with a Lambda OCSP responder, you must grant AWS IoT permission to invoke the Lambda function after the function is created. To grant the permission, you can use the [add-permission](https://docs.aws.amazon.com//cli/latest/reference/lambda/add-permission.html) CLI command. **Grant permission to your Lambda function using the AWS CLI** 1. After inserting your values, enter the following command. Note that the `statement-id` value must be unique. Replace `Id-1234` with the exact value you have, otherwise, you might get a `ResourceConflictException` error. ``` aws lambda add-permission \ --function-name "ocsp-function" \ --principal "iot.amazonaws.com" \ --action "lambda:InvokeFunction" \ --statement-id "Id-1234" \ --source-arn arn:aws:iot:us-east-1:123456789012:domainconfiguration//* --source-account 123456789012 ``` IoT domain configuration ARNs will follow the following pattern. The service-generated suffix will not be known prior to creation time, thus you must replace the suffix with a `*`. You can update the permission once the domain configuration has been created and the exact ARN is known. `arn:aws:iot:use-east-1:123456789012:domainconfiguration/domain-config-name/service-generated-suffix` 1. If the command succeeds, it returns a permission statement, such as this example. You can continue to the next section to configure OCSP stapling for private endpoints. ``` { "Statement": "{\"Sid\":\"Id-1234\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"iot.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-1:123456789012:function:ocsp-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:iot:us-east-1:123456789012:domainconfiguration/domain-config-name/*\"}}}" } ``` If the command doesn't succeed, it returns an error, such as this example. You'll need to review and correct the error before you continue. ``` An error occurred (AccessDeniedException) when calling the AddPermission operation: User: arn:aws:iam::57EXAMPLE833:user/EXAMPLE-1 is not authorized to perform: lambda:AddPer mission on resource: arn:aws:lambda:us-east-1:123456789012:function:ocsp-function ``` ### Configuring server OCSP stapling for private endpoints #### Console **To configure server certificate OCSP stapling using the AWS IoT console:** 1. From the navigation menu, choose **Settings**, and then choose **Create domain configuration**, or choose an existing domain configuration for a custom domain. 1. If you choose to create a new domain configuration in the previous step, you will see the **Create domain configuration** page. In the **Domain configuration properties** section, choose **Custom domain**. Enter the information to create a domain configuration. If you choose to update an existing domain configuration for a custom domain, you will see the **Domain configuration details** page. Choose **Edit**. 1. To enable OCSP server stapling, choose **Enable server certificate OCSP stapling** in the **Server certificate configurations** subsection. 1. Choose **Create domain configuration** or **Update domain configuration**. #### AWS CLI **To configure server certificate OCSP stapling using AWS CLI:** 1. If you create a new domain configuration for a custom domain, the command to configure server certificate OCSP for private endpoints can look like the following: ``` aws iot create-domain-configuration --domain-configuration-name "myDomainConfigurationName" \ --server-certificate-arns arn:aws:iot:us-east-1:123456789012:cert/f8c1e5480266caef0fdb1bf97dc1c82d7ba2d3e2642c5f25f5ba364fc6b79ba3 \ --server-certificate-config "enableOCSPCheck=true, ocspAuthorizedResponderArn=arn:aws:acm:us-east-1:123456789012:certificate/certificate_ID, ocspLambdaArn=arn:aws:lambda:us-east-1:123456789012:function:my-function" ``` 1. If you update an existing domain configuration for a custom domain, the command to configure server certificate OCSP for private endpoints can look like the following: ``` aws iot update-domain-configuration --domain-configuration-name "myDomainConfigurationName" \ --server-certificate-arns arn:aws:iot:us-east-1:123456789012:cert/f8c1e5480266caef0fdb1bf97dc1c82d7ba2d3e2642c5f25f5ba364fc6b79ba3 \ --server-certificate-config "enableOCSPCheck=true, ocspAuthorizedResponderArn=arn:aws:acm:us-east-1:123456789012:certificate/certificate_ID, ocspLambdaArn=arn:aws:lambda:us-east-1:123456789012:function:my-function" ``` **enableOCSPCheck** This is a Boolean value that indicates whether server OCSP stapling check is enabled or not. To enable server certificate OCSP stapling, this value must be true. **ocspAuthorizedResponderArn** This is a string value of the Amazon Resource Name (ARN) for an X.509 certificate stored in AWS Certificate Manager (ACM). If provided, AWS IoT Core will use this certificate to validate the signature of the received OCSP response. If not provided, AWS IoT Core will use the issuing certificate to validate the responses. The certificate must be in the same AWS account and AWS Region as the domain configuration. For more information about how to register your authorized responder certificate, see [Import certificates into AWS Certificate Manager](https://docs.aws.amazon.com//acm/latest/userguide/import-certificate.html). **ocspLambdaArn** This is a string value of the Amazon Resource Name (ARN) for a Lambda function that acts as a Request for Comments (RFC) 6960-compliant (OCSP) responder, supporting basic OCSP responses. The Lambda function accepts a base64-encoding of the OCSP request which is encoded using the DER format. The Lambda function's response is also a base64-encoded OCSP response in the DER format. The response size must not exceed 4 kilobytes (KiB). The Lambda function must be in the same AWS account and AWS Region as the domain configuration. For more information, see [CreateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateDomainConfiguration.html) and [UpdateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_UpdateDomainConfiguration.html) from the AWS IoT API Reference. ## Important notes for using server certificate OCSP stapling in AWS IoT Core When you use server certificate OCSP in AWS IoT Core, keep the following in mind: 1. AWS IoT Core supports only those OCSP responders that are reachable over public IPv4 addresses. 1. The OCSP stapling feature in AWS IoT Core doesn't support authorized responder. All OCSP responses must be signed by the CA that signed the certificate, and the CA must be part of the certificate chain of the custom domain. 1. The OCSP stapling feature in AWS IoT Core doesn't support custom domains that are created using self-signed certificates. 1. AWS IoT Core calls an OCSP responder every hour and caches the response. If the call to the responder fails, AWS IoT Core will staple the most recent valid response. 1. If `nextUpdateTime` is no longer valid, AWS IoT Core will remove the response from the cache, and TLS handshake will not include the OCSP response data until the next successful call to the OCSP responder. This can happen when the cached response has expired before the server gets a valid response from the OCSP responder. The value of `nextUpdateTime` suggests that the OCSP response will be valid until this time. For more information about `nextUpdateTime`, see [Server certificate OCSP log entries](cwl-format.md#server-ocsp-logs). 1. Sometimes, AWS IoT Core fails to receive the OCSP response or removes the existing OCSP response because it's expired. If situations like these happen, AWS IoT Core will continue to use the server certificate provided by the custom domain without the OCSP response. 1. The size of the OCSP response cannot exceed 4 KiB. ## Troubleshooting server certificate OCSP stapling in AWS IoT Core AWS IoT Core emits the `RetrieveOCSPStapleData.Success` metric and the `RetrieveOCSPStapleData` log entries to CloudWatch. The metric and the log entries can help detect issues related to retrieving OCSP responses. For more information, see [Server certificate OCSP stapling metrics](metrics_dimensions.md#server-ocsp-metrics) and [Server certificate OCSP log entries](cwl-format.md#server-ocsp-logs). # Connect to AWS IoT FIPS endpoints AWS IoT provides endpoints that support the [Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com//compliance/fips/). FIPS compliant endpoints are different from standard AWS endpoints. To interact with AWS IoT in a FIPS-compliant manner, you must use the endpoints described below with your FIPS compliant client. The AWS IoT console is not FIPS compliant. The following sections describe how to access the FIPS compliant AWS IoT endpoints by using the REST API, an SDK, or the AWS CLI. **Topics** + [ ## AWS IoT Core - control plane endpoints ](#iot-connect-fips-control) + [ ## AWS IoT Core - data plane endpoints ](#iot-connect-fips-data) + [ ## AWS IoT Core - credential provider endpoints ](#iot-connect-fips-credential) + [ ## AWS IoT Device Management - jobs data endpoints ](#iot-connect-fips-jobs) + [ ## AWS IoT Device Management - Fleet Hub endpoints ](#iot-connect-fips-fleethub) + [ ## AWS IoT Device Management - secure tunneling endpoints ](#iot-connect-fips-tunnel) + [ ## AWS IoT Device Management - Managed Integrations endpoints ](#mi-fips-endpoints) ## AWS IoT Core - control plane endpoints The FIPS compliant **AWS IoT Core - control plane** endpoints that support the [AWS IoT](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT.html) operations and their related [CLI commands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html) are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Core - control plane** service, and look up the endpoint for your AWS Region. To use the FIPS compliant endpoint when you access the [AWS IoT](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT.html) operations, use the AWS SDK or the REST API with the endpoint that is appropriate for your AWS Region. To use the FIPS compliant endpoint when you run [**aws iot** CLI commands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html), add the **--endpoint** parameter with the appropriate endpoint for your AWS Region to the command. ## AWS IoT Core - data plane endpoints The FIPS compliant **AWS IoT Core - data plane** endpoints are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Core - data plane** service, and look up the endpoint for your AWS Region. You can use the FIPS compliant endpoint for your AWS Region with a FIPS compliant client by using the AWS IoT Device SDK and providing the endpoint to the SDK's connection function in place of your account's default **AWS IoT Core - data plane** endpoint. The connection function is specific to the AWS IoT Device SDK. For an example of a connection function, see the [Connection function in the AWS IoT Device SDK for Python](https://aws.github.io/aws-iot-device-sdk-python-v2/awsiot/mqtt_connection_builder.html). **Note** AWS IoT doesn't support AWS account-specific **AWS IoT Core - data plane** endpoints that are FIPS-compliant. Service features that require an AWS account-specific endpoint in the [Server Name Indication (SNI)](transport-security.md) can't be used. FIPS-compliant **AWS IoT Core - data plane** endpoints can't support [Multi-Account Registration Certificates](x509-client-certs.md#multiple-account-cert), [Custom Domains](iot-custom-endpoints-configurable-custom.md), [Custom Authorizers](custom-authentication.md), and [Configurable Endpoints](iot-custom-endpoints-configurable.md) (including supported [TLS policies](transport-security.md#tls-policy-table)). ## AWS IoT Core - credential provider endpoints The FIPS compliant **AWS IoT Core - credential provider** endpoints are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Core - credential provider** service, and look up the endpoint for your AWS Region. **Note** AWS IoT doesn't support AWS account-specific **AWS IoT Core - credential provider** endpoints that are FIPS-compliant. Service features that require an AWS account-specific endpoint in the [Server Name Indication (SNI)](transport-security.md) can't be used. FIPS-compliant **AWS IoT Core - credential provider** endpoints can't support [Multi-Account Registration Certificates](x509-client-certs.md#multiple-account-cert), [Custom Domains](iot-custom-endpoints-configurable-custom.md), [Custom Authorizers](custom-authentication.md), and [Configurable Endpoints](iot-custom-endpoints-configurable.md) (including supported [TLS policies](transport-security.md#tls-policy-table)). ## AWS IoT Device Management - jobs data endpoints The FIPS compliant **AWS IoT Device Management - jobs data** endpoints are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Device Management - jobs data** service, and look up the endpoint for your AWS Region. To use the FIPS compliant **AWS IoT Device Management - jobs data** endpoint when you run [**aws iot-jobs-data** CLI commands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-jobs-data/index.html), add the **--endpoint** parameter with the appropriate endpoint for your AWS Region to the command. You can also use the REST API with this endpoint. We recommend using `Data-ATS` instead of `iot:Jobs`. `iot:Data-ATS` supports dual-stack endpoints (IPv4 and IPv6) while `iot:Jobs` supports only IPv4. You can use the FIPS compliant endpoint for your AWS Region with a FIPS compliant client by using the AWS IoT Device SDK and providing the endpoint to the SDK's connection function in place of your account's default **AWS IoT Device Management - jobs data** endpoint. The connection function is specific to the AWS IoT Device SDK. For an example of a connection function, see the [Connection function in the AWS IoT Device SDK for Python](https://aws.github.io/aws-iot-device-sdk-python-v2/awsiot/mqtt_connection_builder.html). ## AWS IoT Device Management - Fleet Hub endpoints The FIPS compliant **AWS IoT Device Management - Fleet Hub** endpoints to use with [Fleet Hub for AWS IoT Device Management](https://docs.aws.amazon.com//iot/latest/fleethubuserguide/what-is-aws-iot-monitor.html) [CLI commands](https://docs.aws.amazon.com//cli/latest/reference/iotfleethub/index.html) are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Device Management - Fleet Hub** service, and look up the endpoint for your AWS Region. To use the FIPS compliant **AWS IoT Device Management - Fleet Hub** endpoint when you run [**aws iotfleethub** CLI commands](https://docs.aws.amazon.com//cli/latest/reference/iotfleethub/index.html), add the **--endpoint** parameter with the appropriate endpoint for your AWS Region to the command. You can also use the REST API with this endpoint. ## AWS IoT Device Management - secure tunneling endpoints The FIPS compliant **AWS IoT Device Management - secure tunneling** endpoints for the [AWS IoT secure tunneling API](https://docs.aws.amazon.com//iot/latest/apireference/API_Operations_AWS_IoT_Secure_Tunneling.html) and the corresponding [CLI commands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotsecuretunneling/index.html) are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Device Management - secure tunneling** service, and look up the endpoint for your AWS Region. To use the FIPS compliant **AWS IoT Device Management - secure tunneling** endpoint when you run [**aws iotsecuretunneling** CLI commands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotsecuretunneling/index.html), add the **--endpoint** parameter with the appropriate endpoint for your AWS Region to the command. You can also use the REST API with this endpoint. ## AWS IoT Device Management - Managed Integrations endpoints The FIPS compliant **control plane** endpoints that support the managed integrations operations and their related AWS CLI commands are listed in [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service). In [FIPS Endpoints by Service](https://aws.amazon.com//compliance/fips/#FIPS_Endpoints_by_Service), find the **AWS IoT Device Management - Managed integrations** service, and look up the endpoint for your AWS Region. To use the FIPS compliant endpoint when you access the managed integrations operations, use the AWS SDK or the REST API with the endpoint that is appropriate for your AWS Region. To use the FIPS compliant endpoint when you run managed integrations CLI commands, add the **--endpoint** parameter with the appropriate endpoint for your AWS Region to the command.