Creating and configuring custom domains - Amazon IoT Core
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. With custom domains, you can manage your own server certificates so that you can manage 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.

Note

Amazon IoT Core considers a certificate to be signed by a public CA if it's included in Mozilla's trusted ca-bundle.

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.

  • The leaf certificate must include contain 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 certificate key size is 2048.

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:

  • 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 Amazon Web Services Region.

  • domainName

    The FQDN that your devices use to connect to Amazon IoT Core. Amazon 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. Amazon 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

    Amazon IoT Core currently supports only the DATA service type. When you specify DATA, Amazon 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.

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
Note

After you create your domain configuration, it might take up to 60 minutes until Amazon IoT Core serves your custom server certificates.

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.

Note

If your certificate is invalid, Amazon 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