Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating and configuring custom domains

Domain configurations let you specify a custom fully qualified domain name (FQDN) to connect to Amazon IoT Core. There are many benefits of using 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 Amazon Web Services 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.

Registering server certificates in Amazon certificate manager

Before you create a domain configuration with a custom domain, you must register your server certificate chain in Amazon Certificate Manager (ACM). You can use the following three types of server certificates.

Certificate requirements

See Prerequisites for Importing Certificates for the requirements for importing certificates into ACM. In addition to these requirements, Amazon IoT Core adds the following requirements.

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 *.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 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 in the Amazon 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 API. To learn more about this task and the prerequisites and certificate format requirements, see Importing Certificates.

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 API. To learn more about this task and the prerequisites and certificate format requirements, see Importing Certificates.

Creating a validation certificate

After you import your certificate to ACM, generate a public certificate for your custom domain by using the RequestCertificate 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. 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 API. A domain configuration for a custom domain consists of the following:

The following Amazon 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

For more information, see Managing domain configurations.

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 Amazon IoT domain. This record must point to an Amazon IoT endpoint of type iot:Data-ATS. You can get your endpoint by using the DescribeEndpoint API.

The following Amazon 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 Amazon IoT endpoint. If you create multiple custom domains in the same Amazon Web Services account, alias them to this same iot:Data-ATS endpoint.

Troubleshooting

If you have trouble connecting devices to a custom domain, make sure that Amazon IoT Core has accepted and applied your server certificate. You can verify that Amazon IoT Core has accepted your certificate by using either the Amazon IoT Core console or the Amazon CLI.

To use the Amazon IoT Core console, navigate to the Settings 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 listed in the previous section. If the certificate has the same ARN, Amazon IoT Core will be pick it up and apply it automatically.

To check the certificate status by using the Amazon CLI, call the DescribeDomainConfiguration API and specify your domain configuration name.

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