AWS iot-sitewise medium security documentation change
Summary
Updated documentation to replace ACL file-based authorization with AWS IoT SiteWise EMQX CLI tool and built-in database, including revised steps for managing authorization rules via dashboard and CLI.
Security assessment
The changes shift from manual ACL file editing (error-prone and insecure) to a managed CLI tool and built-in database, reducing misconfiguration risks. Removed direct exposure of admin credentials in API calls (e.g., curl commands with passwords), which could leak sensitive data. Added guidance for secure rule management aligns with access control best practices.
Diff
diff --git a/iot-sitewise/latest/userguide/add-rules-emqx-broker.md b/iot-sitewise/latest/userguide/add-rules-emqx-broker.md index cee989aa9..ca480cfee 100644 --- a//iot-sitewise/latest/userguide/add-rules-emqx-broker.md +++ b//iot-sitewise/latest/userguide/add-rules-emqx-broker.md @@ -5 +5 @@ -# Add rules through the EMQX Dashboard or REST APIs +# Add authorization rules through the EMQX Dashboard for users @@ -7 +7 @@ -Editing the ACL file previously added won't update authorization rules. Instead, you can add or update authorization rules using the EMQX dashboard or the EMQX REST APIs. +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. @@ -11 +11 @@ Editing the ACL file previously added won't update authorization rules. Instead, -Adding authorization rules is advanced configuration step that requires familiarization with ACL file formatting options. For more information creating authorization rules using EMQX, see the [Use ACL File](https://docs.emqx.com/en/emqx/latest/access-control/authz/file.html) section in the _EMQX Docs_ +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_. @@ -34 +34 @@ The EMQX dashboard is only accessible from within the gateway host. If you try t - 5. Choose the **Settings** button within the table on the Authorization screen. Note that this isn't the "Settings" button for the whole page. + 5. Choose the **Permissions** button on the **Built-in Database** row. @@ -36 +36 @@ The EMQX dashboard is only accessible from within the gateway host. If you try t - + 6. 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_. @@ -38 +37,0 @@ The EMQX dashboard is only accessible from within the gateway host. If you try t - 6. In the **ACL file** section, add or update the authorization rules for your business needs. New rules should be added after existing rules. For more guidance on creating rules, see the [Use ACL File](https://docs.emqx.com/en/emqx/latest/access-control/authz/file.html) section in the _EMQX Docs_. @@ -41,0 +41 @@ The EMQX dashboard is only accessible from within the gateway host. If you try t +AWS IoT SiteWise CLI tool using Linux @@ -43 +42,0 @@ The EMQX dashboard is only accessible from within the gateway host. If you try t -EMQX REST APIs using Linux @@ -44,0 +44 @@ EMQX REST APIs using Linux +###### To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Linux: @@ -46 +46 @@ EMQX REST APIs using Linux -###### To view and add authorization rules using a shell environment and the EMQX broker REST APIs + * Add authorization rules for a user using the following format: @@ -48 +48 @@ EMQX REST APIs using Linux - 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.html#emqx-broker-username-password-auth). + /greengrass/v2/bin/swe-emqx-cli auth add your-username your-action your-permission your-topic [your-action-permission-topic] @@ -50 +49,0 @@ EMQX REST APIs using Linux - 2. View your existing authorization rules by running the following command. Replace the admin password with your own login information. @@ -52,7 +50,0 @@ EMQX REST APIs using Linux - curl -s -X 'POST' 'http://localhost:18083/api/v5/login' -H'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{"username": "admin", "password": "your-admin-password" }' \ - | jq -r '.token' \ - | xargs -I {} curl 'http://localhost:18083/api/v5/authorization/sources/file' \ - -H 'Authorization: Bearer {}' \ - | jq . @@ -60 +51,0 @@ EMQX REST APIs using Linux - 3. Update the ACL file using the following command: @@ -62 +53 @@ EMQX REST APIs using Linux - docker exec -it emqx vi /opt/emqx/data/authz/acl.conf +###### Example Add authorization rules for a user @@ -64 +55 @@ EMQX REST APIs using Linux -Press the "i" key to enter the editing mode, then add or update the rules for your business needs. For more guidance on creating rules, see the [Use ACL File](https://docs.emqx.com/en/emqx/latest/access-control/authz/file.html) section in the _EMQX Docs_. +This example shows how to add rules for a user named `system1`: @@ -66 +56,0 @@ Press the "i" key to enter the editing mode, then add or update the rules for yo -When you have finished editing, press ":wq" and then press "enter" or "return" to save and edit the file editor. @@ -68 +58,4 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t - 4. Add the basic authorization rules created previously. For more information, see [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](./authorization-rules-emqx-broker.html). + /greengrass/v2/bin/swe-emqx-cli auth add system1 \ + publish allow "sensors/#" \ + subscribe allow "control/#" \ + all deny "#" @@ -70 +63 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t - 5. Add or update the authorization rules as needed. +###### Example : View authorization rules for a user @@ -72 +65 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t - 6. Invoke the EMQX API to apply the updated rules using the following command. Replace the admin password with your own login information. Replace the `path-to-rules-file` with your file path to your new authorization rules. +To view authorization rules for the `system1` users, run the following command: @@ -74,9 +66,0 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t - UPDATED_RULES=$(cat path-to-rules-file) - curl -s -X 'POST' 'http://localhost:18083/api/v5/login' -H'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{"username": "admin", "password": "your-admin-password" }' \ - | jq -r '.token' \ - | xargs -I {} curl 'http://localhost:18083/api/v5/authorization/sources/file' \ - -H 'Authorization: Bearer {}' \ - -X 'PUT' \ - --data-raw "{\"enable\":true,\"rules\":\"$UPDATED_RULES\",\"type\":\"file\"}" @@ -83,0 +68 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t + /greengrass/v2/bin/swe-emqx-cli auth list system1 @@ -84,0 +70 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t +###### Example : View all existing authorization rules @@ -85,0 +72 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t +To view all of the authorization rules you currently have, run the following command: @@ -87 +73,0 @@ When you have finished editing, press ":wq" and then press "enter" or "return" t -Your new authorization rules should be in effect after you've invoked the EMQX API. @@ -89 +75 @@ Your new authorization rules should be in effect after you've invoked the EMQX A -EMQX REST APIs using Windows + /greengrass/v2/bin/swe-emqx-cli auth list @@ -90,0 +77 @@ EMQX REST APIs using Windows +###### Example : Delete all authorization rules for a user @@ -92 +79 @@ EMQX REST APIs using Windows -###### To view existing authorization rules using Windows PowerShell and the EMQX broker REST APIs +To delete all of the authorization rules applied to a particular user, run the following command: @@ -94 +80,0 @@ EMQX REST APIs using Windows - 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.html#emqx-broker-username-password-auth). @@ -96 +82 @@ EMQX REST APIs using Windows - 2. View your existing authorization rules by running the following command. Replace the admin password with your own login information. + /greengrass/v2/bin/swe-emqx-cli auth delete system1 @@ -98,3 +84 @@ EMQX REST APIs using Windows - try { - $loginResponse = Invoke-RestMethod -Uri 'http://localhost:18083/api/v5/login' -Method Post -ContentType 'application/json' -Body '{"username": "admin", "password": "your-admin-password"}' - $token = $loginResponse.token +You are prompted to confirm the deletion. @@ -102 +86 @@ EMQX REST APIs using Windows - $viewAuthorizationRuleResponse = Invoke-RestMethod -Uri 'http://localhost:18083/api/v5/authorization/sources/file' -Method Get -Headers @{"Authorization" = "Bearer $token"} +AWS IoT SiteWise CLI tool using Windows @@ -104,4 +87,0 @@ EMQX REST APIs using Windows - $viewAuthorizationRuleResponse | ConvertTo-Json - } catch { - Write-Output "Failed to fetch current authorization rules: $_" - } @@ -109 +89 @@ EMQX REST APIs using Windows - 3. Update the ACL file using the following command: +###### To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Windows PowerShell: @@ -111 +91 @@ EMQX REST APIs using Windows - C:\greengrass\v2\work\aws.greengrass.clientdevices.mqtt.EMQX\v2\data\authz\acl.conf + * Add authorization rules for a user using the following format: @@ -113 +93 @@ EMQX REST APIs using Windows -Add or update the rules for your business needs. For more guidance on creating rules, see the [Use ACL File](https://docs.emqx.com/en/emqx/latest/access-control/authz/file.html) section in the _EMQX Docs_. + C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add your-username your-action your-permission your-topic [your-action-permission-topic] @@ -115 +94,0 @@ Add or update the rules for your business needs. For more guidance on creating r - 4. Add or update the authorization rules as needed. @@ -117 +95,0 @@ Add or update the rules for your business needs. For more guidance on creating r - 5. Invoke the EMQX API to apply the updated rules using the following command. Replace the admin password with your own login information. @@ -119,4 +96,0 @@ Add or update the rules for your business needs. For more guidance on creating r - try { - # Login and get token - $loginResponse = Invoke-RestMethod -Uri 'http://localhost:18083/api/v5/login' -Method Post -ContentType 'application/json' -Body '{"username": "admin", "password": "your-admin-password"}' - $token = $loginResponse.token @@ -124,2 +98 @@ Add or update the rules for your business needs. For more guidance on creating r - # Read the content of the ACL file from the C volume - $aclContent = Get-Content -Path "C:\greengrass\v2\work\aws.greengrass.clientdevices.mqtt.EMQX\v2\data\authz\acl.conf" | Out-String +###### Example : Add authorization rules for a user @@ -127,6 +100 @@ Add or update the rules for your business needs. For more guidance on creating r - # Prepare the request body - $body = @{ - enable = $true - rules = $aclContent - type = "file" - } | ConvertTo-Json +This example shows how to add rules for a user named `system1`: @@ -134,5 +101,0 @@ Add or update the rules for your business needs. For more guidance on creating r - # Update authorization rules - $updateAuthorizationRuleResponse = Invoke-RestMethod -Uri 'http://localhost:18083/api/v5/authorization/sources/file' -Method Put -Headers @{ - "Authorization" = "Bearer $token" - "Content-Type" = "application/json" - } -Body $body @@ -140,2 +103,4 @@ Add or update the rules for your business needs. For more guidance on creating r - # Output the response - $updateAuthorizationRuleResponse | ConvertTo-Json + C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add system1 ` + publish allow "sensors/#" ` + subscribe allow "control/#" ` + all deny "#" @@ -143,4 +108 @@ Add or update the rules for your business needs. For more guidance on creating r - Write-Output "Updated authorization rules successfully!" - } catch { - Write-Output "Failed to update authorization rules: $_" - } +###### Example : View authorization rules for a user @@ -147,0 +110 @@ Add or update the rules for your business needs. For more guidance on creating r +To view authorization rules for the `system1` users, run the following command: @@ -149,0 +113,17 @@ Add or update the rules for your business needs. For more guidance on creating r + 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.