You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/iot-hub/authenticate-authorize-sas.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ author: SoniaLopezBravo
6
6
ms.service: azure-iot-hub
7
7
ms.author: sonialopez
8
8
ms.topic: conceptual
9
-
ms.date: 09/01/2023
9
+
ms.date: 03/20/2025
10
10
ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Architecture']
11
11
---
12
12
@@ -27,7 +27,7 @@ IoT Hub uses *permissions* to grant access to each IoT hub endpoint. Permissions
27
27
28
28
## Authentication and authorization
29
29
30
-
*Authentication* is the process of proving that you are who you say you are. Authentication verifies the identity of a user or device to IoT Hub. It's sometimes shortened to *AuthN*. *Authorization* is the process of confirming permissions for an authenticated user or device on IoT Hub. It specifies what resources and commands you're allowed to access, and what you can do with those resources and commands. Authorization is sometimes shortened to *AuthZ*.
30
+
*Authentication* is the process of proving that you're who you say you are. Authentication verifies the identity of a user or device to IoT Hub. Authentication is sometimes shortened to *AuthN*. *Authorization* is the process of confirming permissions for an authenticated user or device on IoT Hub. It specifies what resources and commands you're allowed to access, and what you can do with those resources and commands. Authorization is sometimes shortened to *AuthZ*.
31
31
32
32
This article describes authentication and authorization using **Shared access signatures**, which lets you group permissions and grant them to applications using access keys and signed security tokens. You can also use symmetric keys or shared access keys to authenticate a device with IoT Hub. SAS tokens provide authentication for each call made by the device to IoT Hub by associating the symmetric key to each call.
33
33
@@ -62,10 +62,10 @@ You can use the following permissions to control access to your IoT hub:
* The **RegistryRead** permission is used by back-end cloud services and grants the following access:
65
-
* Read access to the identity registry. For more information, see [Identity registry](iot-hub-devguide-identity-registry.md).
65
+
* Read access to the identity registry. For more information, see [Understand the identity registry in your IoT hub](iot-hub-devguide-identity-registry.md).
66
66
67
67
* The **RegistryReadWrite** permission is used by back-end cloud services and grants the following access:
68
-
* Read and write access to the identity registry. For more information, see [Identity registry](iot-hub-devguide-identity-registry.md).
68
+
* Read and write access to the identity registry. For more information, see [Understand the identity registry in your IoT hub](iot-hub-devguide-identity-registry.md).
69
69
70
70
### Per-device security credentials
71
71
@@ -100,7 +100,7 @@ The result, which grants access to read all device identities in the identity re
100
100
101
101
For more examples, see [Generate SAS tokens](#generate-sas-tokens).
102
102
103
-
For services, SAS tokens only grant permissions at the IoT Hub level. That is, a service authenticating with a token based on the **service** policy will be able to perform all the operations granted by the **ServiceConnect** permission. These operations include receiving device-to-cloud messages, sending cloud-to-device messages, and so on. If you want to grant more granular access to your services, for example, limiting a service to only sending cloud-to-device messages, you can use Microsoft Entra ID. To learn more, see [Authenticate with Microsoft Entra ID](authenticate-authorize-azure-ad.md).
103
+
For services, SAS tokens only grant permissions at the IoT Hub level. That is, a service authenticating with a token based on the **service** policy is able to perform all the operations granted by the **ServiceConnect** permission. These operations include receiving device-to-cloud messages, sending cloud-to-device messages, and so on. If you want to grant more granular access to your services, for example, limiting a service to only sending cloud-to-device messages, you can use Microsoft Entra ID. To learn more, see [Control access to IoT Hub by using Microsoft Entra ID](authenticate-authorize-azure-ad.md).
104
104
105
105
## Use SAS tokens from devices
106
106
@@ -150,7 +150,7 @@ The two main scenarios for using shared access policies to access device functio
*[token services](#create-a-token-service-to-integrate-existing-devices) used to implement custom authentication schemes.
152
152
153
-
Since the shared access policy can potentially grant access to connect as any device, it is important to use the correct resource URI when creating SAS tokens. This setting is especially important for token services, which have to scope the token to a specific device using the resource URI. This point is less relevant for protocol gateways as they are already mediating traffic for all devices.
153
+
Since the shared access policy can potentially grant access to connect as any device, it's important to use the correct resource URI when creating SAS tokens. This setting is especially important for token services, which have to scope the token to a specific device using the resource URI. This point is less relevant for protocol gateways as they're already mediating traffic for all devices.
154
154
155
155
As an example, a token service using the precreated shared access policy called **device** would create a token with the following parameters:
156
156
@@ -200,19 +200,19 @@ Here are the main steps of the token service pattern:
200
200
201
201
The token service can set the token expiration as desired. When the token expires, the IoT hub severs the device/module connection. Then, the device/module must request a new token from the token service. A short expiry time increases the load on both the device/module and the token service.
202
202
203
-
For a device/module to connect to your hub, you must still add it to the IoT Hub identity registry—even though it is using a token and not a key to connect. Therefore, you can continue to use per-device/per-module access control by enabling or disabling device/module identities in the identity registry. This approach mitigates the risks of using tokens with long expiry times.
203
+
For a device/module to connect to your hub, you must still add it to the IoT Hub identity registry—even though it's using a token and not a key to connect. Therefore, you can continue to use per-device/per-module access control by enabling or disabling device/module identities in the identity registry. This approach mitigates the risks of using tokens with long expiry times.
204
204
205
205
### Comparison with a custom gateway
206
206
207
-
The token service pattern is the recommended way to implement a custom identity registry/authentication scheme with IoT Hub. This pattern is recommended because IoT Hub continues to handle most of the solution traffic. However, if the custom authentication scheme is so intertwined with the protocol, you may require a *custom gateway* to process all the traffic. An example of such a scenario is using [Transport Layer Security (TLS) and preshared keys (PSKs)](https://tools.ietf.org/html/rfc4279). For more information, see [How an IoT Edge device can be used as a gateway](../iot-edge/iot-edge-as-gateway.md).
207
+
The token service pattern is the recommended way to implement a custom identity registry/authentication scheme with IoT Hub. This pattern is recommended because IoT Hub continues to handle most of the solution traffic. However, if the custom authentication scheme is so intertwined with the protocol, you might require a *custom gateway* to process all the traffic. An example of such a scenario is using [Transport Layer Security (TLS) and preshared keys (PSKs)](https://tools.ietf.org/html/rfc4279). For more information, see [How an IoT Edge device can be used as a gateway](../iot-edge/iot-edge-as-gateway.md).
208
208
209
209
## Generate SAS tokens
210
210
211
211
Azure IoT SDKs automatically generate tokens, but some scenarios do require you to generate and use SAS tokens directly, including:
212
212
213
213
* The direct use of the MQTT, AMQP, or HTTPS surfaces.
214
214
215
-
* The implementation of the token service pattern, as explained in the [Create a token service](#create-a-token-service-to-integrate-existing-devices) section.
215
+
* The implementation of the token service pattern, as explained in the [Create a token service to integrate existing devices](#create-a-token-service-to-integrate-existing-devices) section.
216
216
217
217
A token signed with a shared access key grants access to all the functionality associated with the shared access policy permissions. A token signed with a device identity's symmetric key only grants the **DeviceConnect** permission for the associated device identity.
218
218
@@ -228,7 +228,7 @@ Here are the expected values:
228
228
229
229
| Value | Description |
230
230
| --- | --- |
231
-
| {signature} |An HMAC-SHA256 signature string of the form: `{URL-encoded-resourceURI} + "\n" + expiry`. **Important**: The key is decoded from base64 and used as key to perform the HMAC-SHA256 computation. |
231
+
| {signature-string} |An HMAC-SHA256 signature string of the form: `{URL-encoded-resourceURI} + "\n" + expiry`. **Important**: The key is decoded from base64 and used as key to perform the HMAC-SHA256 computation. |
232
232
| {resourceURI} |URI prefix (by segment) of the endpoints that can be accessed with this token, starting with host name of the IoT hub (no protocol). SAS tokens granted to backend services are scoped to the IoT hub level; for example, `myHub.azure-devices.net`. SAS tokens granted to devices must be scoped to an individual device; for example, `myHub.azure-devices.net/devices/device1`. |
233
233
| {expiry} |UTF8 strings for number of seconds since the epoch 00:00:00 UTC on 1 January 1970. |
234
234
| {URL-encoded-resourceURI} |Lower case URL-encoding of the lower case resource URI |
@@ -379,20 +379,20 @@ Password (You can generate a SAS token with the CLI extension command [az iot hu
> The [Azure IoT SDKs](iot-hub-devguide-sdks.md) automatically generate tokens when connecting to the service. In some cases, the Azure IoT SDKs do not support all the protocols or all the authentication methods.
382
+
> The [Azure IoT Hub SDKs](iot-hub-devguide-sdks.md) automatically generate tokens when connecting to the service. In some cases, the Azure IoT SDKs don't support all the protocols or all the authentication methods.
383
383
384
384
### Special considerations for SASL PLAIN
385
385
386
386
When using SASL PLAIN with AMQP, a client connecting to an IoT hub can use a single token for each TCP connection. When the token expires, the TCP connection disconnects from the service and triggers a reconnection. This behavior, while not problematic for a back-end app, is damaging for a device app for the following reasons:
387
387
388
388
* Gateways usually connect on behalf of many devices. When using SASL PLAIN, they have to create a distinct TCP connection for each device connecting to an IoT hub. This scenario considerably increases the consumption of power and networking resources, and increases the latency of each device connection.
389
389
390
-
*Resource-constrained devices are adversely affected by the increased use of resources to reconnect after each token expiration.
390
+
*The increased use of resources to reconnect after each token expiration adversely affects resource-constrained devices.
391
391
392
392
## Next steps
393
393
394
-
Now that you have learned how to control access IoT Hub, you may be interested in the following IoT Hub developer guide topics:
394
+
Now that you know how to control access to IoT Hub, you might be interested in the following IoT Hub developer guide articles:
395
395
396
-
*[Use device twins to synchronize state and configurations](iot-hub-devguide-device-twins.md)
397
-
*[Invoke a direct method on a device](iot-hub-devguide-direct-methods.md)
396
+
*[Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md)
397
+
*[Understand and invoke direct methods from IoT Hub](iot-hub-devguide-direct-methods.md)
398
398
*[Schedule jobs on multiple devices](iot-hub-devguide-jobs.md)
0 commit comments