Skip to content

Commit 2f3d26f

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #290138 from PatAltimore/patricka-release-aio-ga
Add MQTT broker authentication state store keys
2 parents daa1bc9 + 772c3da commit 2f3d26f

File tree

1 file changed

+267
-5
lines changed

1 file changed

+267
-5
lines changed

‎articles/iot-operations/manage-mqtt-broker/howto-configure-authorization.md

Lines changed: 267 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.subservice: azure-mqtt-broker
77
ms.topic: how-to
88
ms.custom:
99
- ignite-2023
10-
ms.date: 11/02/2024
10+
ms.date: 11/08/2024
1111

1212
#CustomerIntent: As an operator, I want to configure authorization so that I have secure MQTT broker communications.
1313
ms.service: azure-iot-operations
@@ -43,7 +43,7 @@ The following example shows how to create a *BrokerAuthorization* resource using
4343

4444
# [Bicep](#tab/bicep)
4545

46-
To edit the default endpoint, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.
46+
To edit an authorization policy, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.
4747

4848
```bicep
4949
param aioInstanceName string = '<AIO_INSTANCE_NAME>'
@@ -170,7 +170,7 @@ Because the `principals` field is a logical OR, you can further restrict access
170170

171171
# [Portal](#tab/portal)
172172

173-
In the **Broker authorization details** for your authorization policy, use the following configuration:
173+
In the broker authorization rules for your authorization policy, use the following configuration:
174174

175175
```json
176176
[
@@ -207,6 +207,8 @@ In the **Broker authorization details** for your authorization policy, use the f
207207

208208
# [Bicep](#tab/bicep)
209209

210+
To edit an authorization policy, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.
211+
210212
```bicep
211213
param aioInstanceName string = '<AIO_INSTANCE_NAME>'
212214
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
@@ -331,7 +333,7 @@ As the application has an authorization attribute called `authz-sat`, there's no
331333

332334
# [Portal](#tab/portal)
333335

334-
In the **Broker authorization details** for your authorization policy, use the following configuration:
336+
In the Broker authorization rules for your authorization policy, use the following configuration:
335337

336338
```json
337339
[
@@ -370,6 +372,8 @@ In the **Broker authorization details** for your authorization policy, use the f
370372

371373
# [Bicep](#tab/bicep)
372374

375+
To edit an authorization policy, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.
376+
373377
```bicep
374378
param aioInstanceName string = '<AIO_INSTANCE_NAME>'
375379
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
@@ -475,7 +479,265 @@ To set up authorization for clients that use the DSS, provide the following perm
475479
- Permission to publish to the system key value store `$services/statestore/_any_/command/invoke/request` topic
476480
- Permission to subscribe to the response-topic (set during initial publish as a parameter) `<response_topic>/#`
477481

478-
For more information about DSS authorization, see [state store keys](https://github.com/Azure/iotedge-broker/blob/main/docs/authorization/readme.md#state-store-keys).
482+
### State store keys
483+
484+
The state store is accessed over the MQTT broker on topic `statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke`.
485+
Since clients have access to the topic, you can specify keys and access levels under the `stateStoreResources` section of the MQTT broker `brokerResources` configuration.
486+
487+
The `stateStoreResources` section format consists of access level, a pattern indicator, and the pattern.
488+
489+
# [Portal](#tab/portal)
490+
491+
Include the `stateStoreResources` section in the rules for your authorization policy.
492+
493+
```json
494+
"stateStoreResources": [
495+
{
496+
"method": "", // Values: read, write, readwrite
497+
"keyType": "", //Values: string, pattern, binary. Default is pattern
498+
"keys": [
499+
// List of patterns to match
500+
]
501+
},
502+
]
503+
```
504+
505+
# [Bicep](#tab/bicep)
506+
507+
In Bicep, include the `stateStoreResources` section in your authorization policy.
508+
509+
```bicep
510+
stateStoreResources: [
511+
{
512+
method: '' // Values: read, write, readwrite
513+
keyType: '' //Values: string, pattern, binary. Default is pattern
514+
keys: [
515+
// List of patterns to match
516+
]
517+
}
518+
{
519+
method: 'ReadWrite'
520+
keyType: 'Binary'
521+
keys: [
522+
'xxxxxxxxxxxxxxxxxxxx'
523+
]
524+
}
525+
]
526+
```
527+
528+
# [Kubernetes](#tab/kubernetes)
529+
530+
In your custom resource definition, include the `stateStoreResources` section in your authorization policy.
531+
532+
``` yaml
533+
stateStoreResources:
534+
- method: # Values: read, write, readwrite
535+
keyType: # Values: string, pattern, binary. Default is pattern
536+
keys:
537+
- # List of patterns to match
538+
```
539+
540+
---
541+
542+
The `method` field specifies the access level.
543+
- Read access is specified with `read`, write access with `write`, and both with `readwrite`.
544+
- Access level is required.
545+
- Read access level implies the actions of `get` and `keynotify`.
546+
- Write access level implies the actions of `set`, `del`, and `vdel`.
547+
548+
The `keyType` field specifies the type of key matching.
549+
- `pattern` to use *glob* style pattern matching
550+
- `string` to do exact match, for example when a key contains characters that might be otherwise matched as a pattern (`*`, `?`, `[0-9]`)
551+
- `binary` to match a binary key
552+
553+
The `keys` field specifies the keys to match. The keys can be specified as *Glob* style patterns, token substitutions, or exact strings.
554+
- *Glob* style examples:
555+
- `colors/*`: All keys under the "colors/" prefix
556+
- `number[0-9]`: Any key from "number0" to "number9"
557+
- `char?`: Any key with prefix "char" and a single digit suffix, like "charA"
558+
- `*`: Full access to all keys.
559+
- State store keys also support token substitution when key type is `pattern` and curly braces are reserved for this purpose. Token substitution examples:
560+
- `clients/{principal.clientId}/*`
561+
- `usernames/{principal.username}/*`
562+
- `rooms/{principal.attributes.room}/*`
563+
564+
Here's an example of how you might author your state store resources:
565+
566+
# [Portal](#tab/portal)
567+
568+
In the Broker authorization rules for your authorization policy, add a similar configuration:
569+
570+
```json
571+
[
572+
{
573+
"brokerResources": [
574+
{
575+
"clientIds": [
576+
"{principal.attributes.building}*"
577+
],
578+
"method": "Connect"
579+
},
580+
{
581+
"method": "Publish",
582+
"topics": [
583+
"sensors/{principal.attributes.building}/{principal.clientId}/telemetry/*"
584+
]
585+
},
586+
{
587+
"method": "Subscribe",
588+
"topics": [
589+
"commands/{principal.attributes.organization}"
590+
]
591+
}
592+
],
593+
"principals": {
594+
"attributes": [
595+
{
596+
"building": "17",
597+
"organization": "contoso"
598+
}
599+
],
600+
"usernames": [
601+
"temperature-sensor",
602+
"humidity-sensor"
603+
]
604+
},
605+
"stateStoreResources": [
606+
{
607+
"method": "Read",
608+
"keyType": "Pattern",
609+
"keys": [
610+
"myreadkey",
611+
"myotherkey?",
612+
"mynumerickeysuffix[0-9]",
613+
"clients/{principal.clientId}/*"
614+
]
615+
},
616+
{
617+
"method": "ReadWrite",
618+
"keyType": "Binary",
619+
"keys": [
620+
"xxxxxxxxxxxxxxxxxxxx"
621+
]
622+
}
623+
]
624+
}
625+
]
626+
```
627+
628+
# [Bicep](#tab/bicep)
629+
630+
To edit an authorization policy, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.
631+
632+
```bicep
633+
param aioInstanceName string = '<AIO_INSTANCE_NAME>'
634+
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
635+
param policyName string = '<POLICY_NAME>'
636+
637+
resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
638+
name: aioInstanceName
639+
}
640+
641+
resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
642+
name: customLocationName
643+
}
644+
645+
resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
646+
parent: aioInstance
647+
name: 'default'
648+
}
649+
650+
resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-11-01' = {
651+
parent: defaultBroker
652+
name: policyName
653+
extendedLocation: {
654+
name: customLocation.id
655+
type: 'CustomLocation'
656+
}
657+
properties: {
658+
authorizationPolicies: {
659+
cache: 'Enabled'
660+
rules: [
661+
{
662+
principals: {
663+
usernames: [
664+
'temperature-sensor'
665+
'humidity-sensor'
666+
]
667+
attributes: [
668+
{
669+
city: 'seattle'
670+
organization: 'contoso'
671+
}
672+
]
673+
}
674+
brokerResources: [
675+
{
676+
method: 'Connect'
677+
}
678+
{
679+
method: 'Publish'
680+
topics: [
681+
'/telemetry/{principal.username}'
682+
'/telemetry/{principal.attributes.organization}'
683+
]
684+
}
685+
{
686+
method: 'Subscribe'
687+
topics: [
688+
'/commands/{principal.attributes.organization}'
689+
]
690+
}
691+
]
692+
stateStoreResources: [
693+
{
694+
method: 'Read'
695+
keyType: 'Pattern'
696+
keys: [
697+
'myreadkey'
698+
'myotherkey?'
699+
'mynumerickeysuffix[0-9]'
700+
'clients/{principal.clientId}/*'
701+
]
702+
}
703+
{
704+
method: 'ReadWrite'
705+
keyType: 'Binary'
706+
keys: [
707+
'xxxxxxxxxxxxxxxxxxxx'
708+
]
709+
}
710+
]
711+
}
712+
]
713+
}
714+
}
715+
}
716+
```
717+
718+
Deploy the Bicep file using Azure CLI.
719+
720+
```azurecli
721+
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
722+
```
723+
724+
# [Kubernetes](#tab/kubernetes)
725+
726+
``` yaml
727+
stateStoreResources:
728+
- method: Read # Read includes Get, Notify
729+
keyType: "pattern" # string, pattern, binary
730+
keys:
731+
- "myreadkey" # explicit read access on key: myreadkey
732+
- "myotherkey?" # single digit wildcard
733+
- "mynumerickeysuffix[0-9]" # single digit number range
734+
- "clients/{principal.clientId}/*" # use token substitution and a wildcard for per-client sandboxing
735+
- method: ReadWrite # ReadWrite access includes Get, Notify, Set, Del
736+
keyType: "binary" # binary keys have exact match, no patterns
737+
keys:
738+
- "xxxxxxxxxxxxxxxxxxxx" # base-64 encoded binary key.
739+
```
740+
---
479741

480742
## Update authorization
481743

0 commit comments

Comments
 (0)