Share via

Azure IoT Hub SAS token authentication – what username should be used for connection?

Revati Dharmadhikari 20 Reputation points
2026-04-27T07:00:36.8766667+00:00

Hello Team,

I am working with Azure IoT Hub and using SAS token–based authentication for connecting to the hub. The SAS token generation part is already resolved, but I need clarification specifically regarding the username that should be used during the connection.?

Azure IoT Hub
Azure IoT Hub

An Azure service that enables bidirectional communication between internet of things (IoT) devices and applications.

Answer accepted by question author

  1. Anshika Varshney 9,905 Reputation points Microsoft External Staff Moderator
    2026-05-01T07:50:33.9333333+00:00

    Hi Revati Dharmadhikari,

    Good question, this is something that can be a bit confusing when working with SAS authentication in IoT Hub.

    Based on your scenario, your username format is actually correct, but the issue usually comes from how the SAS token is generated and scoped, not just the username itself.

    What the correct username should look like

    For MQTT device connection, the expected username format is

    {your-iot-hub-hostname}/{device-id}/?api-version=2021-04-12

    Example contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

    Also

    • client id should be the device id
    • password should be the SAS token

    Key point that often causes failure

    Even if the username is correct, authentication will fail if the SAS token is generated incorrectly or from the wrong scope

    This is the most common issue in this scenario.

    IoT Hub supports two types of SAS tokens

    1 device scoped SAS token 2 IoT Hub level SAS token using shared access policy

    For device connections using MQTT

    you must use device scoped SAS tokens

    If you generate the SAS token using a shared access policy like iothubowner

    • it may not work for device level MQTT authentication
    • even though username format is correct

    This is because IoT Hub expects the token to match the device identity stored in the identity registry [learn.microsoft.com]

    What to verify step by step

    Here are the main things to check:

    First, confirm SAS token scope

    • make sure the token is generated using device id
    • resource URI should include devices/device-id

    If this is missing, authentication will fail

    Second, check resource URI inside SAS token

    It should follow this pattern

    your hub hostname followed by devices and device id

    If resource URI is incorrect, signature validation fails

    Third, check token expiry

    • SAS tokens are time based
    • expired tokens will silently fail authentication

    Try generating a fresh token and test again

    Fourth, confirm device identity exists in IoT Hub

    • device id must be registered in IoT Hub
    • SAS token must match that device

    IoT Hub validates identity using stored symmetric keys [learn.microsoft.com]

    Fifth, check protocol requirements

    For MQTT

    • port should be 8883
    • TLS must be enabled
    • correct API version should be included in username

    Incorrect protocol setup can also cause connection failure

    You asked whether a SAS token generated from shared access policy can be used directly

    • for device MQTT connection, no
    • you should use device scoped SAS token or device connection string

    This is the reason your connection is failing even with correct username.

    In short

    • your username format looks correct
    • main issue is likely SAS token scope
    • use device scoped SAS token instead of hub level policy
    • verify resource URI and expiry
    • ensure device exists in IoT Hub

    I hope this helps. Do let me know if you have any further queries.

    If this answers your query, please do click Accept Answer and Yes for was this answer helpful.

    Thankyou!

    2 people found this answer helpful.
    0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Q&A Assist
    2026-04-27T07:00:51.6+00:00
    AI generated content. This question contains an answer created with AI from Q&A Assist. Learn more

    For SAS token–based authentication to Azure IoT Hub, the username depends on the protocol and whether the connection is from a device or a module.

    For a device using MQTT directly (no SDK):

    • ClientId: use the device ID
      • ClientId = {device-id}
    • Username: use the IoT Hub host name and device ID with API version:
      • Username = {iotHub-hostname}/{device-id}/?api-version=2021-04-12
      • Example: contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12
    • Password: the SAS token in the form:
      • SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    For a module using MQTT directly:

    • ClientId: {device-id}/{module-id}
    • Username: <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12
    • Password: SAS token associated with the module identity.

    For AMQP with SASL PLAIN:

    • If using IoT hub–level SAS policy:
      • username = {policyName}@sas.root.{iothubName}
    • If using a device-scoped SAS token:
      • username = {deviceId}@sas.{iothubname}
    • In both cases, the password is the SAS token.

    For HTTPS:

    • The SAS token is not used as a username; instead, it is sent in the HTTP Authorization header:
      • Authorization: SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    In all cases, {iothubhostname} is the full CNAME of the IoT hub, for example myhub.azure-devices.net, and deviceId is case-sensitive.

    References:

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.