How to resolve Kepware Azure IoT hub MQTT agent communication failures?

Question

How to resolve Kepware Azure IoT hub MQTT agent communication failures?

Tim Parsons 0

Support Request Summary — Azure IoT Hub MQTT Authentication Failure with Kepware We are attempting to connect Kepware KEPServerEX IoT Gateway (MQTT Agent) to our Azure IoT Hub device kepware_acc_staug_002, but Azure consistently returns:

MQTT agent MqttSecurityException 'Agent' failed to connect - reason: 'Not authorized to connect'

This happens immediately after a successful TLS connection, which confirms:

DNS resolution works

Port 8883 is open

TLS handshake succeeds

The MQTT CONNECT packet is accepted

Network or firewall issues are not the cause

We have validated that the IoT Hub MQTT endpoint is reachable:

MQTT agent 'Minibuck' is connected to broker 'ssl://IOT-ACC-StAug-DB.azure-devices.net:8883'

But IoT Hub immediately rejects authentication.

What we have already tried (condensed technical checklist) 1. SAS Token Validity Generated SAS tokens using:

Our own PowerShell script

  Azure Cloud Shell (`az iot hub generate-sas-token`) — multiple attempts  
  Verified SAS token structure: `sr=`, `sig=`, `se=` all present
  Verified tokens are single-line, no truncation, no invalid characters
  Confirmed the SAS token resource URI matches the HostName and DeviceId exactly

2. Kepware Credential Alignment Updated Kepware MQTT Username to match the exact sr= host casing from the SAS token

Verified MQTT Username format as per Azure documentation: {hostname}/{deviceId}/?api-version=2018-06-30

Ensured:

Client ID = deviceId Username = exact host/deviceId/api-version Password = full SAS token 3. Device Configuration in Azure

Device exists: kepware_acc_staug_002

Status is Enabled

Primary key is present

Using the Primary Device Connection String, not policy keys

Confirmed no duplicate device IDs and no trailing whitespace

4. Hub & Device Properties

Verified no regeneration of device keys during testing

Verified SAS tokens were signed with the correct SharedAccessKey

Hub name: IOT-ACC-StAug-DB

Device path: /devices/kepware_acc_staug_002

5. Kepware Operational Checks

Kepware IoT Gateway service runs correctly

TLS v1.2 is enabled

No certificate errors

Kepware consistently reports successful connection to the broker before the auth failure

Symptoms

Every connection attempt results in the same sequence:

MQTT agent 'Minibuck' is connected to broker 'ssl://IOT-ACC-StAug-DB.azure-devices.net:8883'
MQTT agent MqttSecurityException 'Agent' failed to connect - reason: 'Not authorized to connect'
MQTT agent MqttException failed to InterruptedException

What we need from Microsoft

We need assistance determining why Azure IoT Hub is rejecting MQTT authentication despite:

Valid SAS tokens generated via Azure CLI

Correctly formatted username/clientId

Matching casing between Hub Hostname, SAS token, and Username

Enabled device with correct primary key

Successful TLS connect

This looks like an authentication-layer rejection at IoT Hub and we need help reviewing the relevant logs or device-level configuration issues that could cause persistent "Not authorized to connect" responses even with verified credentials.

If you’d like, I can also prepare a second attachment for Microsoft showing:

The exact sr= and se= fields of the SAS token

The Kepware username string

The relevant Kepware log excerpt

A diagram of the Kepware → IoT Hub flow

Just say the word.Here is a clean, concise, professional explanation you can paste directly into a Microsoft support ticket.

This version explains the issue clearly without overwhelming detail, while proving you’ve ruled out all the usual causes.

Sridhar M 2,675 Reputation points Microsoft External Staff Moderator

2025-11-20T18:18:59.4866667+00:00

Hi Tim Parsons

Thank you for Reaching us about the Kepware Azure IoT hub MQTT agent communication failures issue. We have begun looking into it and will share our suggestions with you as soon as possible. If you have any additional details or concerns in the meantime, please let us know. We appreciate your patience while we work on this.
Sridhar M 2,675 Reputation points Microsoft External Staff Moderator

2025-11-20T19:33:13.5733333+00:00
Hi Tim Parsons

Since TLS and basic broker reachability are confirmed, the “Not authorized to connect” CONNACK is almost always down to username/api-version mismatch or a SAS token that doesn’t match what IoT Hub expects. Below is a focused checklist and a quick repro test that will tell us where the mismatch is (Kepware vs. token vs. hub).

Make the MQTT Username match exactly what IoT Hub expects

IoT Hub’s MQTT username must be:

{iotHub-hostname}/{deviceId}/?api-version=2021-04-12

Example: IOT-ACC-StAug-DB.azure-devices.net/kepware_acc_staug_002/?api-version=2021-04-12 [learn.microsoft.com]

Note: The official docs now show api-version=2021-04-12. Older versions like 2018-06-30 typically still work, but I’ve seen strict parsing in clients cause edge cases—so it’s worth updating to the current one. [learn.microsoft.com]

ClientId must be the deviceId: kepware_acc_staug_002. [learn.microsoft.com]

Verify the SAS token (Password) is URL‑encoded and scoped to the device

IoT Hub expects the password to be a SAS token in this format:

SharedAccessSignature sig={URL-ENCODED signature}&se={expiryEpochSeconds}&sr={URL-ENCODED resourceUri}

Critical details:

sr must be the device URI, i.e. IOT-ACC-StAug-DB.azure-devices.net/devices/kepware_acc_staug_002 (no scheme, and URL‑encoded in the token as %2F etc.). [learn.microsoft.com], [learn.microsoft.com]

sig must be URL‑encoded (e.g., + → %2B, = → %3D). Using an unencoded HMAC output is a common reason for immediate 5=Not Authorized. [learn.microsoft.com]

Do not include skn (that’s only for hub-level policy tokens, not per‑device tokens). [learn.microsoft.com]

The Azure CLI generates a correctly encoded token; copy it verbatim into Kepware’s Password field:

Shell

az iot hub generate-sas-token \

--hub-name IOT-ACC-StAug-DB \

--device-id kepware_acc_staug_002 \

--duration 3600

``

This produces SharedAccessSignature sr=...&sig=...&se=... with sr pointing to /devices/{device} and all URL-encoding done for you. [learn.microsoft.com]

Confirm the device identity and ID characters

The device must exist and be Enabled (you’ve already checked). [learn.microsoft.com]

Your deviceId kepware_acc_staug_002 is valid—_ (underscore) is allowed. [learn.microsoft.com]

Align clocks to avoid “immediate expiry” rejections

If the Kepware host clock is skewed (or timezone/RTC wrong), IoT Hub can treat the SAS se= as expired and drop the connection with unauthorized right after CONNECT. Please ensure the Kepware server’s system time is NTP‑synced. (The IoT Hub error guidance calls out token expiration patterns commonly surfacing as 401003/Unauthorized.) [learn.microsoft.com]

1 answer

Your answer

Sridhar M 2,675 Reputation points Microsoft External Staff Moderator

2025-11-20T18:18:59.4866667+00:00

Hi Tim Parsons

Thank you for Reaching us about the Kepware Azure IoT hub MQTT agent communication failures issue. We have begun looking into it and will share our suggestions with you as soon as possible. If you have any additional details or concerns in the meantime, please let us know. We appreciate your patience while we work on this.

Answer 1

Hello Tim Parsons,
I understand you are encountering a persistent MqttSecurityException ("Not authorized to connect") when connecting Kepware to Azure IoT Hub via MQTT, despite a successful TLS handshake and network validation.

Based on the detailed context you provided, the network and TLS layers are functioning correctly. The error occurring immediately after the TLS handshake confirms that the IoT Hub is rejecting the specific MQTT CONNECT packet credentials.

This is almost exclusively caused by a mismatch in the strict formatting requirements Azure IoT Hub enforces for the MQTT protocol fields (Username, ClientID, and Password). Even a minor deviation here causes an immediate disconnect.

**
I would suggest you to please verify the following three configurations in your Kepware IoT Gateway agent.

1.Validate the MQTT "User Name" Field

This is the most common cause of 401/Not Authorized errors in direct MQTT connections. Azure IoT Hub requires a specific string format that includes the API version. If the api-version is missing, auth fails.

Format: {IoT Hub Hostname}/{Device ID}/?api-version=2021-04-12
Your Configuration should look exactly like this: IOT-ACC-StAug-DB.azure-devices.net/kepware_acc_staug_002/?api-version=2021-04-12
- Check: Ensure the Hub Hostname is the full FQDN.
- Check: Ensure the /?api-version=2021-04-12 is appended at the end.

2.Validate the MQTT "Client ID" Field

In the MQTT protocol, Azure IoT Hub strictly requires the MQTT Client ID to be identical to the Device ID registered in the hub.

Kepware Setting: In the IoT Gateway agent settings, look for the Client ID field.
Value: kepware_acc_staug_002
Note: If Kepware is generating a random Client ID or appending a string to it, the connection will be rejected.

3.Validate the SAS Token (Password) Structure

You mentioned using Azure CLI to generate the token, which is good. However, confirm the "Resource URI" (sr) embedded within that token matches the casing of your inputs exactly.

The token should look like: SharedAccessSignature sr=IOT-ACC-StAug-DB.azure-devices.net%2Fdevices%2Fkepware_acc_staug_002&sig=...&se=...
Double Check: Paste the generated token into the Password field in Kepware. Ensure no trailing spaces were copied.

4.Isolation Test (Recommended)

To rule out Kepware-specific formatting issues, try connecting with a standalone tool like MQTT Explorer or MQTT.fx using the exact same credentials:

Host: IOT-ACC-StAug-DB.azure-devices.net
Port: 8883
Username: (As defined in Step 1)
Password: (Your SAS Token)
Client ID: kepware_acc_staug_002
TLS: On (CA Certificate required)

If this tool connects successfully, the credentials are valid, and the issue lies in how Kepware is constructing the packet (e.g., hidden characters or specific TLS version settings). If this tool also fails, the issue is definitely with the SAS token generation or Device ID casing.

Reference:

Share via

How to resolve Kepware Azure IoT hub MQTT agent communication failures?

1 answer

Your answer