Skip to content

Commit 71b39b5

Browse files
committed
Metadata and links updated, minor Acrolinx fixes to improve score
1 parent 7705988 commit 71b39b5

File tree

1 file changed

+15
-15
lines changed

1 file changed

+15
-15
lines changed

articles/iot-hub/authenticate-authorize-sas.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: SoniaLopezBravo
66
ms.service: azure-iot-hub
77
ms.author: sonialopez
88
ms.topic: conceptual
9-
ms.date: 09/01/2023
9+
ms.date: 03/20/2025
1010
ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Architecture']
1111
---
1212

@@ -27,7 +27,7 @@ IoT Hub uses *permissions* to grant access to each IoT hub endpoint. Permissions
2727

2828
## Authentication and authorization
2929

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*.
3131

3232
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.
3333

@@ -62,10 +62,10 @@ You can use the following permissions to control access to your IoT hub:
6262
* Receive device twin desired property notifications and update device twin reported properties.
6363

6464
* 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).
6666

6767
* 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).
6969

7070
### Per-device security credentials
7171

@@ -100,7 +100,7 @@ The result, which grants access to read all device identities in the identity re
100100

101101
For more examples, see [Generate SAS tokens](#generate-sas-tokens).
102102

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).
104104

105105
## Use SAS tokens from devices
106106

@@ -150,7 +150,7 @@ The two main scenarios for using shared access policies to access device functio
150150
* [cloud protocol gateways](iot-hub-devguide-endpoints.md),
151151
* [token services](#create-a-token-service-to-integrate-existing-devices) used to implement custom authentication schemes.
152152

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.
154154

155155
As an example, a token service using the precreated shared access policy called **device** would create a token with the following parameters:
156156

@@ -200,19 +200,19 @@ Here are the main steps of the token service pattern:
200200
201201
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.
202202

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.
204204

205205
### Comparison with a custom gateway
206206

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).
208208

209209
## Generate SAS tokens
210210

211211
Azure IoT SDKs automatically generate tokens, but some scenarios do require you to generate and use SAS tokens directly, including:
212212

213213
* The direct use of the MQTT, AMQP, or HTTPS surfaces.
214214

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.
216216

217217
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.
218218

@@ -228,7 +228,7 @@ Here are the expected values:
228228

229229
| Value | Description |
230230
| --- | --- |
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. |
232232
| {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`. |
233233
| {expiry} |UTF8 strings for number of seconds since the epoch 00:00:00 UTC on 1 January 1970. |
234234
| {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
379379
`SharedAccessSignature sr=iothubname.azure-devices.net%2fdevices%2fDeviceId&sig=kPszxZZZZZZZZZZZZZZZZZAhLT%2bV7o%3d&se=1487709501`
380380

381381
> [!NOTE]
382-
> 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.
383383
384384
### Special considerations for SASL PLAIN
385385

386386
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:
387387

388388
* 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.
389389

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.
391391

392392
## Next steps
393393

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:
395395

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)
398398
* [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md)

0 commit comments

Comments
 (0)