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).

Connect an application to the EMQX broker on Amazon IoT SiteWise Edge

The EMQX broker uses Transport Layer Security (TLS) on port 8883 to encrypt all communications, ensuring your data remains protected during transmission. This section walks you through the steps to establish connections between your applications and the EMQX broker. Following these steps helps maintain the integrity and confidentiality of your industrial data. The connection process involves two main approaches: using automated IP discovery through components, or manually configuring DNS names and IP addresses as Subject Alternative Names (SANs) in your TLS certificates. Each method has its own advantages depending on your network setup and security requirements. This documentation will guide you through both options.

Configure TLS for secure connections to the EMQX broker on Amazon IoT SiteWise Edge

By default, Amazon IoT Greengrass generates a TLS server certificate for the EMQX broker that is signed by the core device certificate authority (CA). For more information, see Connecting client devices to an Amazon IoT Greengrass Core device with an MQTT broker.

Retrieve the TLS certificate

To get the CA certificate run the following command on the gateway host:

Linux

Run the following command in a shell session on the gateway host:

/greengrass/v2/bin/swe-emqx-cli cert

This command displays the certificate location and prints the certificate's content.

You can alternatively save the certificate to a file using this command:

/greengrass/v2/bin/swe-emqx-cli cert --output /path/to/certificate.pem

Windows

Run the following command in a PowerShell session on the gateway host:

C:\greengrass\v2\bin\swe-emqx-cli.ps1 cert

This command displays the certificate location and prints the certificate's content.

You can alternatively save the certificate to a file using this command:

C:\greengrass\v2\bin\swe-emqx-cli.ps1 cert --output C:\path\to\certificate.pem

The CLI automatically locates the certificate regardless of the exact path on your system.

Copy the contents of the ca.pem file to the external application that you're connecting to the broker. Save it as BrokerCoreDeviceCA.pem.

Add custom DNS names/IP addresses to the TLS server certificate

The subject alternative name (SAN) on the cert generated by Amazon IoT Greengrass is localhost. When establishing a TLS connection from outside of the gateway host, the TLS verification step fails because the broker’s hostname does not match the hostname of localhost on the server certificate.

To address mismatched hostname issue, Amazon IoT Greengrass provides two ways of managing core device endpoints. This section covers both options. For more detailed information, see Manage core device endpoints in the Amazon IoT Greengrass Version 2 Developer Guide.

Automated IP discovery

This option allows your core device to automatically discover its IP address and add it as a Subject Alternative Name (SAN) to the broker certificate.

1. Add the aws.greengrass.clientdevices.IPDetector component to your core device’s deployment.

2. Deploy the changes to your device

3. Wait for deployment to complete.

   After the deployment completes, you can establish a secure TLS connection using the broker's IP address.

   The IP address is automatically added as a SAN to the broker certificate.

Manual DNS and IP Configuration

You can manually add DNS names and IP addresses as Subject Alternative Names (SANs) to your TLS certificate. This method is useful when you have configured a DNS name for your gateway host.

Important

If you are using the IPDetector component, remove it from your deployment before proceeding. The IPDetector component overrides manual endpoint configurations.

To manually configure endpoints

1. Navigate to the Amazon IoT SiteWise console.

2. In the left navigation, choose Edge gateways in the Edge section.

3. Choose the gateway to configure.

4. In the Edge gateway configuration section, choose your Greengrass core device url. The core device's page appears.

5. Choose the Client devices tab.

6. Choose Manage endpoints.

7. In the Manage endpoints dialog box, enter the DNS name(s) and any IP addresses you want to add as SANs. Use port 8883.

8. Choose Update.

The broker's TLS server certificate updates automatically to include your new endpoints.

To verify the TLS server certificate update using Linux

1. Start a shell session on your gateway host.

   docker exec emqx openssl x509 -in ./data/cert.pem -text -noout | grep -A1 "Subject Alternative Name"

2. The command returns an output similar to the following:

   X509v3 Subject Alternative Name: 
   DNS:endpoint_you_added, DNS:localhost

3. Verify that your endpoint appears in the list of SANs.

To verify the TLS server certificate update using Windows

1. Start a shell session on your gateway host.

   (Get-PfxCertificate -FilePath "C:\greengrass\v2\work\aws.greengrass.clientdevices.mqtt.EMQX\v2\data\cert.pem").Extensions | Where-Object { $_.Oid.FriendlyName -eq "Subject Alternative Name" } | ForEach-Object { "Subject Alternative Name:", ($_.Format($true) -split "`n")[0..1] }

2. The command returns an output similar to the following:

   Subject Alternative Name:
   DNS Name=your-endpoint
   DNS Name=localhost

3. Verify that the endpoint you added is in the list of SANs.

Test the EMQX broker connection on Amazon IoT SiteWise Edge

After configuring your EMQX broker with TLS certificates and authentication credentials, it's important to verify that your setup works correctly. Testing the connection helps ensure that your security configurations are properly implemented and that clients can successfully establish encrypted connections to the broker. This section demonstrates how to test your broker connection using the Mosquitto command line interface (CLI) client, a widely-used MQTT client tool that supports TLS encryption and authentication.

Use Mosquitto CLI client to test the EMQX broker connection

In this step we will use the mosquitto CLI client to test our setup and make sure we can connect successfully to the broker using the username and password we created earlier. To get the BrokerCoreDeviceCA.pem follow steps under Step 3: Setting up TLS.

mosquitto_sub -h hostname|ip address \
    -p 8883 \
    -t "#" \
    -q 1 \
    -u username -P password \
    --cafile BrokerCoreDeviceCA.pem

At this point, all users have access to publish and subscribe to all topics on the broker. Proceed to Set up authorization rules for Amazon IoT SiteWise Edge in EMQX.

Use your own CA

Amazon IoT Greengrass outlines how to configure your own client device auth component to use your own certificate authority (CA). The client device auth component (aws.greengrass.clientdevices.Auth) authenticates client devices and authorizes client device actions. For more information, see Using your own certificate authority in the Amazon IoT Greengrass Version 2 Developer Guide.

To use your own CA, add the aws.greengrass.clientdevices.Auth component to your deployment so that you can specify a custom configuration.

Open port 8883 for external firewall connections

Linux

In your Linux host firewall rule, add an inbound rule for port 8883 to allow incoming connections from outside of the gateway host. If there are any firewalls in place, ensure that incoming TLS connections on port 8883 are allowed.

Windows

In your Microsoft Windows host firewall rule, add an inbound rule for port 8883 to allow incoming connections from outside of the gateway host. Ensure the rule is an allow rule, of type port, specifying port 8883. You can configure this according to your network configuration to allow connections from your external applications to the broker.