# Connect an application to the EMQX broker on AWS 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.
**Topics**
+ [Configure TLS for secure connections to the EMQX broker on AWS IoT SiteWise Edge](#configure-tls-emqx-broker)
+ [Test the EMQX broker connection on AWS IoT SiteWise Edge](#test-emqx-connection)
+ [Use your own CA](#configure-tls-custom-ca)
+ [Open port 8883 for external firewall connections](#emqx-firewall)
## Configure TLS for secure connections to the EMQX broker on AWS IoT SiteWise Edge
By default, AWS 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 AWS IoT Greengrass Core device with an MQTT broker](https://docs.aws.amazon.com/greengrass/v2/developerguide/connecting-to-mqtt.html).
### 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 AWS 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, AWS IoT Greengrass provides two ways of managing core device endpoints. This section covers both options. For more detailed information, see [Manage core device endpoints](https://docs.aws.amazon.com/greengrass/v2/developerguide/manage-core-device-endpoints.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
+ To connect to the EMQX broker using the core device's IP address, use the Automated IP discovery section.
+ To connect to the EMQX broker using a DNS name instead of IP address, you use the Manual management section.
------
#### [ 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.
1. Deploy the changes to your device
1. 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 [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the left navigation, choose **Edge gateways** in the **Edge** section.
1. Choose the gateway to configure.
1. In the **Edge gateway configuration** section, choose your **Greengrass core device** url. The core device's page appears.
1. Choose the **Client devices** tab.
1. Choose **Manage endpoints**.
1. In the Manage endpoints dialog box, enter the DNS name(s) and any IP addresses you want to add as SANs. Use port 8883.
1. 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"
```
1. The command returns an output similar to the following:
```
X509v3 Subject Alternative Name:
DNS:endpoint_you_added, DNS:localhost
```
1. 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] }
```
1. The command returns an output similar to the following:
```
Subject Alternative Name:
DNS Name=your-endpoint
DNS Name=localhost
```
1. Verify that the endpoint you added is in the list of SANs.
------
## Test the EMQX broker connection on AWS 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
```
**Note**
You may get an SSL:verify error if the hostname/IP address you are connecting to does not match the Subject Alternative Name (SAN) that is on the CA cert you're passing to the client. See "Adding custom DNS names/IP addresses to the TLS server cert" under Step 3: Setting up TLS for how to get a certificate with the correct SAN.
At this point, all users have access to publish and subscribe to all topics on the broker. Proceed to [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](authorization-rules-emqx-broker.md).
## Use your own CA
AWS 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](https://docs.aws.amazon.com/greengrass/v2/developerguide/connecting-to-mqtt.html#use-your-own-CA) in the *AWS 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.
------