feat: Support username/password local broker authentication #3823

rina23q · 2025-10-17T16:13:31Z

Proposed changes

Support username/password authentication to the MQTT local broker.

Prepare a /etc/tedge/.password file. The first line is read as the password.

testpassword

Then, configure these parameters.

tedge config set mqtt.client.auth.username testuser
tedge config set mqtt.client.auth.password_file /etc/tedge/.password

If encrypted connection is activated in the broker, configure any secure port (e.g. 8883) and give the CA certificate file or the directory (below is example)

tedge config set mqtt.client.port 8883
tedge config set mqtt.client.auth.ca_file /etc/mosquitto/certs/ca.crt

Todo:

Confirm tedge mqtt pub/sub works
Confirm tedge-agent & tedge-mapper-c8y work with mosquitto bridge
Confirm tedge-agent & tedge-mapper-c8y works with build-in bridge
Confirm it works with non-c8y cloud
Write system tests
Extend the user guide

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
Documentation Update (if none of the other choices apply)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue

#3807

Checklist

I have read the CONTRIBUTING doc
I have signed the CLA (in all commits with git commit -s. You can activate automatic signing by running just prepare-dev once)
I ran just format as mentioned in CODING_GUIDELINES
I used just check as mentioned in CODING_GUIDELINES
I have added tests that prove my fix is effective or that my feature works
I have added necessary documentation (if appropriate)

Further comments

codecov · 2025-10-17T16:26:12Z

Codecov Report

❌ Patch coverage is 8.41121% with 98 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/common/mqtt_channel/src/config.rs	0.00%	54 Missing ⚠️
..._config/src/tedge_toml/tedge_config/mqtt_config.rs	26.66%	21 Missing and 1 partial ⚠️
crates/core/tedge/src/cli/mqtt/publish.rs	11.11%	6 Missing and 2 partials ⚠️
crates/core/tedge/src/cli/mqtt/subscribe.rs	0.00%	8 Missing ⚠️
crates/extensions/tedge_mqtt_bridge/src/lib.rs	0.00%	4 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

rina23q · 2025-10-21T15:04:52Z

crates/common/mqtt_channel/src/config.rs

+        None => Err(CertificateError::IoError {
+            path: path.as_ref().to_owned(),
+            error: std::io::Error::other("File content is empty"),
+        }),


This error has to be removed as the MQTT specification states that you can send a username without password. However, both username and password are required for MqttOptions::set_credentials() in rumqttc, so I'm not sure how empty password is addressed in rumqttc.

I checked how MqttOptions::set_cedentials() behaves in the packet level.

In the MQTT specs level, there are username flag and password flag. So, "empty password" and "password not set" are different. The former, the password flag is set but password is empty string. The latter, the password flag itself isn't set.

"Empty password" exmaple:

mosquitto_pub -h 127.0.0.1 -u testuser -P "" -t test -p 1883 -m message

"Password not set" example:

mosquitto_pub -h 127.0.0.1 -u testuser -t test -p 1883 -m message

Back to rumqttc. Their API offers only set_credentials(username, password). I provided the empty string to the second argument as below.

mqttoptions.set_credentials("username", "");

Then, I ran the rumqttc client and confirmed the password flag was not set in the CONNECT packet. This means, rumqttc treats "empty password" equals to "password not set".

didier-wenzek · 2025-10-22T12:58:33Z

crates/common/mqtt_channel/src/config.rs

+#[derive(Debug, Clone)]
+enum ClientAuthConfig {
+    Cert(ClientAuthCertConfig),
+    User(ClientAuthUserConfig),


Password is clearer.

Suggested change

User(ClientAuthUserConfig),

Pass(ClientAuthPassConfig),

Agreed.

By the way, I created this enum because at first I thought user would use either certificate or username/password for authentication. However, after I saw the MQTT specifications, client certificate is in the Transport Layer and username/password is in the Application Layer. Then, I started feeling, we should support the case using both. Can you confirm this?

While a broker can accept both, a thin-edge MQTT client only needs to be configured to authenticate itself either using a certificate or a password, not both. Using a certificate is recommended.

But the username can still be required when using certificates right? At least that is my experience when using the Azure EventGrid MQTT endpoint (not that this is a cloud related topic, but more to give an example of an MQTT broker being configured a specific way).

But the username can still be required when using certificates right?

I think so. For example, mosquitto has use_identity_as_username settings, if it's set to true, the certificate's CN is used as a username. Password won't be set.

Ok good to know. I don't think we need to go to the level of having a "use_identity_as_username" equivalent in thin-edge.io...I'd much rather let the users configure the values themselves, and then possibly allow users to set a value using variables ${.common_name} (but we can do template evaluation that later).

I'll refactor the code so that user has an opportunity to set username (and password if necessary) together with client certificates since it's possible in the MQTT specifications. I believe it's better thin-edge supports whatever the MQTT specifications allow.

didier-wenzek · 2025-10-22T13:58:02Z

crates/common/mqtt_channel/src/config.rs

+#[derive(Debug, Clone)]
+struct ClientAuthUserConfig {
+    username: String,
+    password: String,


I would consider to use zeroize

Suggested change

password: String,

password: Zeroizing<String>,

didier-wenzek · 2025-10-22T14:02:05Z

crates/common/tedge_config/src/tedge_toml/tedge_config/mqtt_config.rs

    }
+
+    // Return username and password if they are set
+    pub fn username_and_password(&self) -> Option<(String, String)> {


Better to return a ClientAuthUserConfig as defined in the mqtt_channel::config module.

Suggested change

pub fn username_and_password(&self) -> Option<(String, String)> {

pub fn username_and_password(&self) -> Option<mqtt_channel::config::ClientAuthUserConfig> {

didier-wenzek · 2025-10-22T14:12:06Z

crates/extensions/tedge_mqtt_bridge/src/lib.rs

        let auth_config = tedge_config.mqtt_client_auth_config();
+
+        if let Some((username, password)) = auth_config.username_and_password() {
+            local_config.set_credentials(username, password);
+        }


I would design the config API in such a way that no change is required for the clients connecting the local MQTT bus. So that, all the required auth settings are captured in a single method call to mqtt_client_auth_config whatever their kind (certificates or password based).

didier-wenzek · 2025-10-22T14:25:13Z

crates/core/tedge/src/cli/mqtt/subscribe.rs

-    if let Some(client_auth) = cmd.client_auth_config.as_ref() {
-        config.with_client_auth(&client_auth.cert_file, &client_auth.key_file)?;
+    if let Some(MqttAuthClientConfig::Cert(client_auth)) = cmd.client_auth_config.as_ref() {
+        config.with_client_auth_cert_key(&client_auth.cert_file, &client_auth.key_file)?;
+    }
+
+    if let Some(MqttAuthClientConfig::User(client_auth_user)) = cmd.client_auth_config.as_ref() {
+        config.with_client_auth_user_pass(
+            &client_auth_user.username,
+            client_auth_user.password_file.clone(),
+        )?;
    }


An MQTT client should be agnostic to how the user is authenticated. I would move this logic into the tedge config so we can write:

if let Some(client_auth) = cmd.client_auth_config.as_ref() { config.with_client_auth(client_auth)?;

This will avoid code duplication across tedge mqtt sub, pub, mappers and the agent.

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

github-actions · 2025-10-22T16:22:29Z

Robot Results

✅ Passed	❌ Failed	⏭️ Skipped	Total	Pass %	⏱️ Duration
717	0	3	717	100	2h10m9.512111s

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

albinsuresh · 2025-10-24T07:59:26Z

docs/src/operate/security/mqtt-tls-configuration.md

 2. Server authentication
 3. Server + client authentication

+In addition, authentication with username and password is supported. See [here](#username-password-authentication) for details.


I'd have added that to the above list, especially since No authentication is a part of that list.

albinsuresh · 2025-10-24T08:00:28Z

docs/src/operate/security/mqtt-tls-configuration.md

+## Username/Password authentication {#username-password-authentication}
+
+When a local MQTT broker requires username/password authentication,
+the %%te%% components also need to know this username and password.


Suggested change

the %%te%% components also need to know this username and password.

the %%te%% components need to provide this username and password.

albinsuresh · 2025-10-24T08:02:24Z

docs/src/operate/security/mqtt-tls-configuration.md

+```sh title="file: <file_path>"
+YOUR_PASSWORD
+```
+


Add one line about restricting the access levels(600) to that file as soon as it is created?

albinsuresh · 2025-10-24T08:20:37Z

tests/RobotFramework/tests/mqtt/local_broker_authentication/local_broker_authentication.robot

+    Configure MQTT client    host=${CONTAINER_1_HOSTNAME}    port=1884
+    Start Service    tedge-agent
+
+TLS Setup


Optional suggestion: Instead of two variants TLS Setup and No TLS Setup, why not just keep a single Setup keyword that takes tld_enabled as an argument? Especially since these keywords are already taking the use_builtin_bridge argument?

use_builtin_bridge makes really one-liner difference (sudo tedge config set mqtt.bridge.built_in ${use_builtin_bridge}), while TLS/no TLS need more different setup (bootstrap_args, port, set/unset some tedge config keys, different listener file). Then eventually I thought it would be easier to read, if there are two different Setup keys.

albinsuresh · 2025-10-24T08:24:28Z

tests/RobotFramework/tests/mqtt/local_broker_authentication/local_broker_authentication.robot

+    [Arguments]    ${use_builtin_bridge}
+
+    # Parent
+    ${CONTAINER_1}=    Setup    bootstrap_args=--no-secure    register=${True}    connect=${False}


Suggested change

${CONTAINER_1}= Setup bootstrap_args=--no-secure register=${True} connect=${False}

${PARENT_SN}= Setup bootstrap_args=--no-secure register=${True} connect=${False}

We've always used these naming conventions to distinguish the containers easily.

albinsuresh · 2025-10-24T08:24:41Z

tests/RobotFramework/tests/mqtt/local_broker_authentication/local_broker_authentication.robot

+    Connect Mapper    c8y
+
+    # Child
+    ${CONTAINER_2}=    Setup    bootstrap_args=--no-secure    register=${False}    connect=${False}


Suggested change

${CONTAINER_2}= Setup bootstrap_args=--no-secure register=${False} connect=${False}

${CHILD_SN}= Setup bootstrap_args=--no-secure register=${False} connect=${False}

albinsuresh · 2025-10-24T08:33:00Z

crates/common/mqtt_channel/src/config.rs

+        pass_file: P,
+    ) -> Result<&mut Self, CertificateError> {
+        debug!(target: "MQTT", "Using client username: {username}");
+        debug!(target: "MQTT", "Using client password: {}", pass_file.as_ref().display());


Suggested change

debug!(target: "MQTT", "Using client password: {}", pass_file.as_ref().display());

debug!(target: "MQTT", "Using client password from: {}", pass_file.as_ref().display());

albinsuresh · 2025-10-24T08:41:22Z

crates/common/mqtt_channel/src/config.rs

+#[derive(Debug, Clone)]
+enum ClientAuthConfig {
+    Cert(ClientAuthCertConfig),
+    User(ClientAuthPassConfig),


Suggested change

User(ClientAuthPassConfig),

Cred(ClientAuthCredConfig),

Short for "credentials".

Okay, I just saw the older discussion on this. For some reason, it didn't appear in the files view during the review.

albinsuresh · 2025-10-24T08:47:58Z

crates/core/tedge/src/cli/mqtt/publish.rs

+    if let Some(MqttAuthClientConfig::Cert(client_auth_cert)) = cmd.client_auth_config.as_ref() {
+        config
+            .with_client_auth_cert_key(&client_auth_cert.cert_file, &client_auth_cert.key_file)?;
+    }
+
+    if let Some(MqttAuthClientConfig::User(client_auth_user)) = cmd.client_auth_config.as_ref() {
+        config.with_client_auth_user_pass(
+            &client_auth_user.username,
+            client_auth_user.password_file.clone(),
+        )?;


Suggested change

if let Some(MqttAuthClientConfig::Cert(client_auth_cert)) = cmd.client_auth_config.as_ref() {

config

.with_client_auth_cert_key(&client_auth_cert.cert_file, &client_auth_cert.key_file)?;

}

if let Some(MqttAuthClientConfig::User(client_auth_user)) = cmd.client_auth_config.as_ref() {

config.with_client_auth_user_pass(

&client_auth_user.username,

client_auth_user.password_file.clone(),

)?;

if let Some(client_auth_config) = cmd.client_auth_config.as_ref() {

match client_auth_config {

MqttAuthClientConfig::Cert(client_auth_cert) => {

config

.with_client_auth_cert_key(&client_auth_cert.cert_file, &client_auth_cert.key_file)?;

}

MqttAuthClientConfig::User(client_auth_user) => {

config.with_client_auth_user_pass(

&client_auth_user.username,

client_auth_user.password_file.clone(),

)?;

}

}

}```

rina23q requested a deployment to Test Pull Request October 17, 2025 16:13 — with GitHub Actions Waiting

rina23q requested a deployment to Test Pull Request October 20, 2025 18:29 — with GitHub Actions Waiting

rina23q requested a deployment to Test Pull Request October 20, 2025 19:25 — with GitHub Actions Waiting

rina23q commented Oct 21, 2025

View reviewed changes

didier-wenzek reviewed Oct 22, 2025

View reviewed changes

rina23q added 2 commits October 22, 2025 15:37

feat: Support username/password local broker authentication

0a4872d

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

test: Add local broker username/password auth system test

f3adf15

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

rina23q force-pushed the feature/3807/support-local-client-username-password-authentication branch from 4a67eee to f3adf15 Compare October 22, 2025 15:44

rina23q temporarily deployed to Test Pull Request October 22, 2025 15:44 — with GitHub Actions Inactive

rina23q temporarily deployed to Test Auto October 22, 2025 16:02 — with GitHub Actions Inactive

rina23q requested a deployment to Test Pull Request October 23, 2025 12:31 — with GitHub Actions Waiting

rina23q marked this pull request as ready for review October 23, 2025 12:33

rina23q requested review from a team, albinsuresh, jarhodes314 and reubenmiller as code owners October 23, 2025 12:33

doc: describe username/password authentication in the user guide

34b2eab

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

rina23q force-pushed the feature/3807/support-local-client-username-password-authentication branch from 0f9b7df to 34b2eab Compare October 23, 2025 13:16

rina23q requested a deployment to Test Pull Request October 23, 2025 13:16 — with GitHub Actions Waiting

fixup! feat: Support username/password local broker authentication

53b2652

Signed-off-by: Rina Fujino <rina.fujino.23@gmail.com>

rina23q temporarily deployed to Test Pull Request October 23, 2025 19:55 — with GitHub Actions Inactive

rina23q temporarily deployed to Test Auto October 24, 2025 07:10 — with GitHub Actions Inactive

albinsuresh reviewed Oct 24, 2025

View reviewed changes

	pub fn username_and_password(&self) -> Option<(String, String)> {
	pub fn username_and_password(&self) -> Option<mqtt_channel::config::ClientAuthUserConfig> {

	the %%te%% components also need to know this username and password.
	the %%te%% components need to provide this username and password.

	${CONTAINER_1}= Setup bootstrap_args=--no-secure register=${True} connect=${False}
	${PARENT_SN}= Setup bootstrap_args=--no-secure register=${True} connect=${False}

	${CONTAINER_2}= Setup bootstrap_args=--no-secure register=${False} connect=${False}
	${CHILD_SN}= Setup bootstrap_args=--no-secure register=${False} connect=${False}

	debug!(target: "MQTT", "Using client password: {}", pass_file.as_ref().display());
	debug!(target: "MQTT", "Using client password from: {}", pass_file.as_ref().display());

feat: Support username/password local broker authentication #3823

Are you sure you want to change the base?

feat: Support username/password local broker authentication #3823

Conversation

rina23q commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Types of changes

Paste Link to the issue

Checklist

Further comments

Uh oh!

codecov bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rina23q Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Robot Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

albinsuresh Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rina23q Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

rina23q commented Oct 17, 2025 •

edited

Loading

codecov bot commented Oct 17, 2025 •

edited

Loading

rina23q Oct 24, 2025 •

edited

Loading

github-actions bot commented Oct 22, 2025 •

edited

Loading

albinsuresh Oct 24, 2025 •

edited

Loading

rina23q Oct 24, 2025 •

edited

Loading