# Connect external applications to the EMQX broker This guide explains how to connect external applications to your AWS IoT SiteWise Edge gateway through an EMQX broker on your deployed MQTT-enabled, V3 gateway. External applications might include custom monitoring tools, third-party visualization software, or legacy systems that need to interact with your industrial data at the edge. We'll cover the configuration steps for both Linux and Microsoft Windows environments, including EMQX deployment configuration, TLS setup for secure connections, and authorization rules to control access to specific topics. **Note** EMQX is not a vendor or supplier for AWS IoT SiteWise Edge. **Important** For securing connections to your gateway, we strongly recommend using certificate-based authentication through the AWS IoT Greengrass client device authentication feature. This method provides robust security through mutual TLS (mTLS) authentication. For more information, see [Connect client devices to core devices](https://docs.aws.amazon.com/greengrass/v2/developerguide/connect-client-devices.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. If you are not able to use certificate based authentication, follow this guide to setup authentication using usernames and passwords. ## Prerequisites + A SiteWise Edge MQTT-enabled, V3 gateway that has been deployed and is online + Access to the gateway host + Access to the AWS IoT SiteWise and AWS IoT Greengrass consoles **Topics** + [Prerequisites](#emqx-broker-prerequisites) + [Message payload format for the EMQX broker on AWS IoT SiteWise Edge](connect-broker-payload-format.md) + [Configure the EMQX broker](configure-emqx-broker.md) + [Connect an application to the EMQX broker on AWS IoT SiteWise Edge](connect-app-to-broker.md) + [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](authorization-rules-emqx-broker.md) # Message payload format for the EMQX broker on AWS IoT SiteWise Edge For the IoT SiteWise publisher component to consume data from your external application and publish it to the AWS IoT SiteWise cloud, the payload sent to the broker must meet specific requirements. Understanding the payload format is key to successful MQTT communication with AWS IoT SiteWise Edge. While the connection setup process is covered in later sections, we present the payload requirements first to help you plan your implementation. ## MQTT topic requirements There are no restrictions on MQTT topic structure, including the number of levels or characters used. However, we recommend that the topic matches the `propertyAlias` field in the payload. **Example property alias** If the MQTT topic is `site1/line1/compressor1/temperature`, ensure the `propertyAlias` matches. ``` { "assetId": "compressor_asset_01", "propertyAlias": "site1/line1/compressor1/temperature", "propertyId": "temperature_sensor_01", "propertyValues": [ { "quality": "GOOD", "timestamp": { "offsetInNanos": 0, "timeInSeconds": 1683000000 }, "value": { "doubleValue": 23.5 } } ] } ``` ## JSON payload structure The MQTT message payload are written in JSON and follow the `PutAssetPropertyValueEntry` message format defined in the [AWS IoT SiteWise API Reference](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html). ``` { "assetId": "string", "propertyAlias": "string", "propertyId": "string", "propertyValues": [ { "quality": "string", "timestamp": { "offsetInNanos": number, "timeInSeconds": number }, "value": { "booleanValue": boolean, "doubleValue": number, "integerValue": number, "stringValue": "string" } } ] } ``` **Note** For a message to be considered valid, only one of the following conditions can be true: The `propertyAlias` is set, or Both `assetId` and `propertyId` are set The `PutAssetPropertyValueEntry` has an `entryId` field that is not required in this context. # Configure the EMQX broker This section covers how to add usernames and passwords. It also covers how to establish a TLS connection from an external source using the added username and password. You can configure the EMQX broker using Linux or Microsoft Windows. **Note** To configure the broker, you need a core device that is setup with the default EMQX configuration in your MQTT-enabled, V3 gateway. **Important** After completing this procedure, we highly recommend configuring authorization rules. For more information, see [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](authorization-rules-emqx-broker.md). Authorization rules for added users enhances security. ## Update the EMQX deployment configuration for authentication **To update the EMQX deployment configuration for authentication** 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, copy your **Greengrass core device** value. Save it for later use. 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot/). 1. On the left navigation, under the **Manage** section, choose **Greengrass devices**, then **Deployments**. 1. Find the core device value you saved earlier and choose that link to open the deployment. 1. Choose the **Actions** dropdown button, then **Revise**. 1. Read the message that appears and then choose **Revise deployment**. The **Specify target** page appears. 1. Choose **Next** until you reach the **Configure components** step. 1. Select the `aws.greengrass.clientdevices.mqtt.EMQX` radio button. 1. Choose the **Configure component** button. A configuration page appears for the component. 1. Under **Configuration update**, choose **Reset to default configuration for component version: 2.\$1.\$1**. 1. Enter the following configuration in the **Configuration to merge** section based on your OS. ------ #### [ Linux ] ``` { "emqxConfig": { "authorization": { "no_match": "allow" }, "listeners": { "tcp": { "default": { "enabled": true, "enable_authn": false } }, "ssl": { "default": { "enabled": true, "enable_authn": true, "ssl_options": { "verify": "verify_none", "fail_if_no_peer_cert": false } } } }, "authentication": { "enable": true, "backend": "built_in_database", "mechanism": "password_based", "password_hash_algorithm": { "iterations": 210000, "mac_fun": "sha512", "name": "pbkdf2" }, "user_id_type": "username" }, "dashboard": { "listeners": { "http": { "bind": 18083 } } } }, "authMode": "bypass", "dockerOptions": "-p 8883:8883 -p 127.0.0.1:1883:1883 -p 127.0.0.1:18083:18083 -v emqx-data:/opt/emqx/data -e EMQX_NODE__NAME=emqx@local", "requiresPrivilege": "true" } ``` ------ #### [ Windows ] ``` { "emqxConfig": { "authorization": { "no_match": "allow" }, "listeners": { "tcp": { "default": { "enabled": true, "enable_authn": false } }, "ssl": { "default": { "enabled": true, "enable_authn": true, "ssl_options": { "verify": "verify_none", "fail_if_no_peer_cert": false } } } }, "authentication": { "enable": true, "backend": "built_in_database", "mechanism": "password_based", "password_hash_algorithm": { "iterations": 210000, "mac_fun": "sha512", "name": "pbkdf2" }, "user_id_type": "username" }, "dashboard": { "listeners": { "http": { "bind": 18083 } } } }, "authMode": "bypass", "requiresPrivilege": "true" } ``` The `dockerOptions` field is only for Linux gateways. ------ 1. Choose **Confirm**. 1. Choose **Next** until you reach the **Review** step. 1. Choose **Deploy**. 1. After the deployment succeeds, proceed to the next step. ## Enable username and password authentication This section shows you how to add usernames and passwords through the EMQX dashboard GUI. **Note** The EMQX-related instructions provided are for reference only. As EMQX documentation and features may change over time, and we do not maintain their documentation, we recommend consulting [EMQX's official documentation](https://docs.emqx.com/en/emqx/latest/) for the most current information. ------ #### [ EMQX Dashboard ] **To enable username and password authentication through the EMQX dashboard** 1. Ensure that you are within the gateway host. 1. Open a browser window and visit [http://localhost:18083/](http://localhost:18083/). 1. Enter the default username of **admin** and the default password of **public**. For more information, see [EMQX Dashboard](https://docs.emqx.com/en/emqx/latest/dashboard/introduction.html#first-login) in the *EMQX Docs*. 1. After login, you are prompted to change your password. Update your password to continue to the EMQX Dashboard. 1. In the left navigation, choose the shield icon, then **Authentication**. 1. In the **Built-in Database** row, choose the **Users** button. 1. Choose the plus sign icon button to add users. An **Add** screen appears. 1. Enter a username and password for the user of the external application. 1. Choose **Save**. The username you chose appears in the **Authentication** page's table. **Note** Existing or default authorization rules apply to the new user. It's recommended to review and adjust them to your external application needs. ------ #### [ EMQX Management with Linux ] Use the AWS IoT SiteWise EMQX CLI tool at `/greengrass/v2/bin/swe-emqx-cli`. **To enable username and password authentication through EMQX Management using Linux** 1. Change the admin password by running the following command: ``` /greengrass/v2/bin/swe-emqx-cli admin change-pwd ``` 1. When prompted, do the following: 1. Enter your current administrator user (default is `admin`) and password (default is `public`). 1. Enter and confirm your new password. If successful, you see the following message: ``` admin password changed successfully ``` 1. Add users for external applications by running the following command: ``` /greengrass/v2/bin/swe-emqx-cli users add ``` 1. When prompted, do the following: 1. Enter the username for the new user. 1. Enter and confirm the password for the new user. If successful, you see the following message: ``` User '[username]' created successfully ``` 1. Verify user configuration by running the following command: ``` /greengrass/v2/bin/swe-emqx-cli users list ``` The output shows all configured users: ``` Users: - [your-added-username] Total users: 1 ``` ------ #### [ EMQX Management with Windows ] Use the AWS IoT SiteWise EMQX CLI tool at one of the following locations: + PowerShell: `C:\greengrass\v2\bin\swe-emqx-cli.ps1` + Command Prompt: `C:\greengrass\v2\bin\swe-emqx-cli.bat` **To enable username and password authentication through EMQX Management using Windows** 1. Change the admin password by running the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 admin change-pwd ``` 1. When prompted, do the following: 1. Enter your current administrator user (default is `admin`) and password (default is `public`). 1. Enter and confirm your new password. If successful, you see the following message: ``` admin password changed successfully ``` 1. Add users for external applications by running the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 users add ``` 1. When prompted, do the following: 1. Enter the username for the new user. 1. Enter and confirm the password for the new user. If successful, you see the following message: ``` User '[username]' created successfully ``` 1. Verify user configuration by running the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 users list ``` The output shows all configured users: ``` Users: - [your-added-username] Total users: 1 ``` ------ # 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. ------ # Set up authorization rules for AWS IoT SiteWise Edge in EMQX EMQX supports adding authorization rules based on identifiers such as username, IP address or client ID. This is useful if you want to limit the number of external applications connecting to various operations or topics. **Topics** + [Configure authorization using the built-in database with Linux](add-auth-rules-database-emqx-broker-linux.md) + [Configure authorization using the built-in database with Windows](add-auth-rules-database-emqx-broker-windows.md) + [Update the EMQX deployment configuration for authorization](update-emqx-broker-authorization.md) + [Add authorization rules through the EMQX Dashboard for users](add-rules-emqx-broker.md) # Configure authorization using the built-in database with Linux When you configure authorization rules, there are two configuration choices that depend on your deployment setup. + **Docker** – If you're running a standard Docker installation without Litmus Edge, use the **Docker bridge gateway** configuration. This is typically the case when you've only deployed AWS IoT SiteWise components. + **Litmus Edge** – If you have Litmus Edge installed on your gateway, use the **Litmus Edge network subnet** configuration. **Note** If you initially configure the Docker bridge gateway and later install Litmus Edge, reconfigure the authorization rules using the Litmus Edge network subnet option to ensure proper communication between all components. **To add basic authorization rules** 1. Verify that the EMQX broker is deployed and running. 1. Start a shell session on your gateway host. ------ #### [ Docker without Litmus Edge ] For standard Docker installation without Litmus Edge, run: ``` /greengrass/v2/bin/swe-emqx-cli acl init ``` ------ #### [ Litmus Edge network subnet ] If you're using Litmus Edge, determine the Litmus Edge network subnet IP: ``` docker network inspect LitmusNetwork | grep IPAM -A9 ``` Note the Subnet value from the output and run the following command. Replace `litmus_subnet_ip` with the Subnet value from the previous step. ``` /greengrass/v2/bin/swe-emqx-cli acl init litmus_subnet_ip ``` ------ The tool automatically creates and applies authorization rules to allow connections from the provided IP address to the broker. It allows access to all topics. This includes the IoT SiteWise OPC UA collector and IoT SiteWise publisher. 1. Proceed to [Update the EMQX deployment configuration for authorization](update-emqx-broker-authorization.md). # Configure authorization using the built-in database with Windows This section covers configuring authorization rules using the built-in database for Windows deployments. **To add basic authorization rules** 1. Verify that the EMQX broker is deployed and running. 1. Run the AWS IoT SiteWise EMQX CLI tool: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 acl init ``` The tool automatically creates and applies ACL rules allowing connections from localhost (127.0.0.1) to the broker. It allows access to all topics. This includes the IoT SiteWise OPC UA collector and IoT SiteWise publisher. 1. Proceed to [Update the EMQX deployment configuration for authorization](update-emqx-broker-authorization.md). # Update the EMQX deployment configuration for authorization **To update the EMQX deployment configuration for authorization** 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, copy your **Greengrass core device** value. Save it for later use. 1. Open the [AWS IoT console](https://console.aws.amazon.com/iot/). 1. On the left navigation, under the **Manage** section, choose **Greengrass devices**, then **Deployments**. 1. Find the core device value you saved earlier and choose that link to open the deployment. 1. Choose the **Actions** dropdown button, then **Revise**. 1. Read the message that appears and then choose **Revise deployment**. The **Specify target** page appears. 1. Choose **Next** until you reach the **Configure components** step. 1. Select the `aws.greengrass.clientdevices.mqtt.EMQX` radio button. 1. Choose the **Configure component** button. A configuration page appears for the component. 1. Under **Configuration update**, choose **Reset to default configuration for component version: 2.\$1.\$1**. 1. Paste the following content in the **Configuration to merge** section based on your OS. ------ #### [ Linux ] ``` { "emqxConfig": { "authorization": { "no_match": "deny", "sources": [ { "type": "built_in_database" }, { "type": "file", "path": "data/authz/acl.conf" } ] }, "listeners": { "tcp": { "default": { "enabled": true, "enable_authn": false } }, "ssl": { "default": { "enabled": true, "enable_authn": true, "ssl_options": { "verify": "verify_none", "fail_if_no_peer_cert": false } } } }, "authentication": { "enable": true, "backend": "built_in_database", "mechanism": "password_based", "password_hash_algorithm": { "iterations": 210000, "mac_fun": "sha512", "name": "pbkdf2" }, "user_id_type": "username" }, "dashboard": { "listeners": { "http": { "bind": 18083 } } } }, "authMode": "bypass", "dockerOptions": "-p 8883:8883 -p 127.0.0.1:1883:1883 -p 127.0.0.1:18083:18083 -v emqx-data:/opt/emqx/data -e EMQX_NODE__NAME=emqx@local", "requiresPrivilege": "true" } ``` ------ #### [ Windows ] ``` { "emqxConfig": { "authorization": { "no_match": "deny", "sources": [ { "type": "built_in_database" }, { "type": "file", "path": "C:\\greengrass\\v2\\work\\aws.greengrass.clientdevices.mqtt.EMQX\\v2\\data\\authz\\acl.conf" } ] }, "listeners": { "tcp": { "default": { "enabled": true, "enable_authn": false } }, "ssl": { "default": { "enabled": true, "enable_authn": true, "ssl_options": { "verify": "verify_none", "fail_if_no_peer_cert": false } } } }, "authentication": { "enable": true, "backend": "built_in_database", "mechanism": "password_based", "password_hash_algorithm": { "iterations": 210000, "mac_fun": "sha512", "name": "pbkdf2" }, "user_id_type": "username" }, "dashboard": { "listeners": { "http": { "bind": 18083 } } } }, "authMode": "bypass", "requiresPrivilege": "true" } ``` ------ 1. Choose **Confirm**. 1. Choose **Next** until you reach the **Review** step. 1. Choose **Deploy**. **Note** From this point onward, you can't edit the ACL file to update the authorization rules. Alternatively, you can proceed to [Add authorization rules through the EMQX Dashboard for users](add-rules-emqx-broker.md) after a successful deployment. # Add authorization rules through the EMQX Dashboard for users You can add or update authorization rules using the EMQX Dashboard or the AWS IoT SiteWise EMQX CLI tool. The AWS IoT SiteWise EMQX CLI tool manages authorization using EMQX's built-in database. **Note** Adding authorization rules is an advanced configuration step that requires understanding of MQTT topic patterns and access control. For more information about creating authorization rules using EMQX's built-in database, see [Use Built-in Database](https://docs.emqx.com/en/emqx/latest/access-control/authz/mnesia.html) in the *EMQX Docs*. **Note** The EMQX-related instructions provided are for reference only. As EMQX documentation and features may change over time, and we do not maintain their documentation, we recommend consulting [EMQX's official documentation](https://docs.emqx.com/en/emqx/latest/) for the most current information. ------ #### [ EMQX dashboard ] This procedure shows how you can add authorization rules on the EMQX dashboard. The EMQX dashboard is only accessible from within the gateway host. If you try to connect from outside of the gateway host, you can't access the dashboard. **To add authorization rules using the EMQX Dashboard** 1. Ensure that you are within the gateway host. 1. Open a browser window and visit [http://localhost:18083/](http://localhost:18083/). 1. Login to the the EMQX dashboard. This procedure assumes that you've changed your default login credentials to something of your choosing. For more information on intial setup, see [Enable username and password authentication](configure-emqx-broker.md#emqx-broker-username-password-auth). 1. Choose the shield icon, then **Authorization** from the dropdown menu. 1. Choose the **Permissions** button on the **Built-in Database** row. 1. In the Built-in Database authorization section, add or update the user authorization rules for your business needs. For more guidance on creating rules, see the [Use Built-in Database](https://docs.emqx.com/en/emqx/latest/access-control/authz/mnesia.html) section in the *EMQX Docs*. ------ #### [ AWS IoT SiteWise CLI tool using Linux ] **To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Linux:** + Add authorization rules for a user using the following format: ``` /greengrass/v2/bin/swe-emqx-cli auth add your-username your-action your-permission your-topic [your-action-permission-topic] ``` **Example Add authorization rules for a user** This example shows how to add rules for a user named `system1`: ``` /greengrass/v2/bin/swe-emqx-cli auth add system1 \ publish allow "sensors/#" \ subscribe allow "control/#" \ all deny "#" ``` **Example : View authorization rules for a user** To view authorization rules for the `system1` users, run the following command: ``` /greengrass/v2/bin/swe-emqx-cli auth list system1 ``` **Example : View all existing authorization rules** To view all of the authorization rules you currently have, run the following command: ``` /greengrass/v2/bin/swe-emqx-cli auth list ``` **Example : Delete all authorization rules for a user** To delete all of the authorization rules applied to a particular user, run the following command: ``` /greengrass/v2/bin/swe-emqx-cli auth delete system1 ``` You are prompted to confirm the deletion. ------ #### [ AWS IoT SiteWise CLI tool using Windows ] **To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Windows PowerShell:** + Add authorization rules for a user using the following format: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add your-username your-action your-permission your-topic [your-action-permission-topic] ``` **Example : Add authorization rules for a user** This example shows how to add rules for a user named `system1`: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add system1 ` publish allow "sensors/#" ` subscribe allow "control/#" ` all deny "#" ``` **Example : View authorization rules for a user** To view authorization rules for the `system1` users, run the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth list system1 ``` **Example : View all existing authorization rules** To view all of the authorization rules you currently have, run the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth list ``` **Example : Delete all authorization rules for a user** To delete all of the authorization rules applied to a particular user, run the following command: ``` C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth delete system1 ``` You are prompted to confirm the deletion. ------