Configure MQTT broker authorization
Important
Azure IoT Operations Preview – enabled by Azure Arc is currently in preview. You shouldn't use this preview software in production environments.
You'll need to deploy a new Azure IoT Operations installation when a generally available release is made available. You won't be able to upgrade a preview installation.
See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
Authorization policies determine what actions the clients can perform on the broker, such as connecting, publishing, or subscribing to topics. Configure MQTT broker to use one or multiple authorization policies with the BrokerAuthorization resource.
You can set to one BrokerAuthorization for each listener. Each BrokerAuthorization resource contains a list of rules that specify the principals and resources for the authorization policies.
Important
To have the BrokerAuthorization configuration apply to a listener, at least one BrokerAuthentication must also be linked to that listener.
Configure BrokerAuthorization for listeners
The specification of a BrokerAuthorization resource has the following fields:
Field Name | Required | Description |
---|---|---|
authorizationPolicies | Yes | This field defines the settings for the authorization policies, such as enableCache and rules. |
enableCache | No | Whether to enable caching for the authorization policies. If set to true , the broker caches the authorization results for each client and topic combination to improve performance and reduce latency. If set to false , the broker evaluates the authorization policies for each client and topic request, to ensure consistency and accuracy. This field is optional and defaults to false . |
rules | No | A list of rules that specify the principals and resources for the authorization policies. Each rule has these subfields: principals and brokerResources. |
principals | Yes | This subfield defines the identities that represent the clients, such as usernames, clientids, and attributes. |
usernames | No | A list of usernames that match the clients. The usernames are case-sensitive and must match the usernames provided by the clients during authentication. |
clientids | No | A list of client IDs that match the clients. The client IDs are case-sensitive and must match the client IDs provided by the clients during connection. |
attributes | No | A list of key-value pairs that match the attributes of the clients. The attributes are case-sensitive and must match the attributes provided by the clients during authentication. |
brokerResources | Yes | This subfield defines the objects that represent the actions or topics, such as method and topics. |
method | Yes | The type of action that the clients can perform on the broker. This subfield is required and can be one of these values: Connect: This value indicates that the clients can connect to the broker. Publish: This value indicates that the clients can publish messages to topics on the broker. Subscribe: This value indicates that the clients can subscribe to topics on the broker. |
topics | No | A list of topics or topic patterns that match the topics that the clients can publish or subscribe to. This subfield is required if the method is Subscribe or Publish. |
The following example shows how to create a BrokerAuthorization resource that defines the authorization policies for a listener named my-listener.
apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
kind: BrokerAuthorization
metadata:
name: "my-authz-policies"
namespace: azure-iot-operations
spec:
authorizationPolicies:
enableCache: true
rules:
- principals:
usernames:
- temperature-sensor
- humidity-sensor
attributes:
- city: "seattle"
organization: "contoso"
brokerResources:
- method: Connect
- method: Publish
topics:
- "/telemetry/{principal.username}"
- "/telemetry/{principal.attributes.organization}"
- method: Subscribe
topics:
- "/commands/{principal.attributes.organization}"
This broker authorization allows clients with usernames temperature-sensor
or humidity-sensor
, or clients with attributes organization
with value contoso
and city
with value seattle
, to:
- Connect to the broker.
- Publish messages to telemetry topics scoped with their usernames and organization. For example:
temperature-sensor
can publish to/telemetry/temperature-sensor
and/telemetry/contoso
.humidity-sensor
can publish to/telemetry/humidity-sensor
and/telemetry/contoso
.some-other-username
can publish to/telemetry/contoso
.
- Subscribe to commands topics scoped with their organization. For example:
temperature-sensor
can subscribe to/commands/contoso
.some-other-username
can subscribe to/commands/contoso
.
To create this BrokerAuthorization resource, apply the YAML manifest to your Kubernetes cluster.
Authorize clients that use X.509 authentication
Clients that use X.509 certificates for authentication can be authorized to access resources based on X.509 properties present on their certificate or their issuing certificates up the chain.
Using attributes
To create rules based on properties from a client's certificate, its root CA, or intermediate CA, define the X.509 attributes in the BrokerAuthorization resource. For more information, see Certificate attributes.
With client certificate subject common name as username
To create authorization policies based on the client certificate subject common name (CN) only, create rules based on the CN.
For example, if a client has a certificate with subject CN = smart-lock
, its username is smart-lock
. From there, create authorization policies as normal.
Authorize clients that use Kubernetes Service Account Tokens
Authorization attributes for SATs are set as part of the Service Account annotations. For example, to add an authorization attribute named group
with value authz-sat
, run the command:
kubectl annotate serviceaccount mqtt-client aio-mq-broker-auth/group=authz-sat
Attribute annotations must begin with aio-mq-broker-auth/
to distinguish them from other annotations.
As the application has an authorization attribute called authz-sat
, there's no need to provide a clientId
or username
. The corresponding BrokerAuthorization resource uses this attribute as a principal, for example:
apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
kind: BrokerAuthorization
metadata:
name: "my-authz-policies"
namespace: azure-iot-operations
spec:
authorizationPolicies:
enableCache: false
rules:
- principals:
attributes:
- group: "authz-sat"
brokerResources:
- method: Connect
- method: Publish
topics:
- "odd-numbered-orders"
- method: Subscribe
topics:
- "orders"
To learn more with an example, see Set up Authorization Policy with Dapr Client.
Distributed state store
MQTT broker provides a distributed state store (DSS) that clients can use to store state. The DSS can also be configured to be highly available.
To set up authorization for clients that use the DSS, provide the following permissions:
- Permission to publish to the system key value store
$services/statestore/_any_/command/invoke/request
topic - Permission to subscribe to the response-topic (set during initial publish as a parameter)
<response_topic>/#
For more information about DSS authorization, see state store keys.
Update authorization
Broker authorization resources can be updated at runtime without restart. All clients connected at the time of the update of policy are disconnected. Changing the policy type is also supported.
kubectl edit brokerauthorization my-authz-policies
Disable authorization
To disable authorization, set authorizationEnabled: false
in the BrokerListener resource. When the policy is set to allow all clients, all authenticated clients can access all operations.
apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
kind: BrokerListener
metadata:
name: "my-listener"
namespace: azure-iot-operations
spec:
brokerRef: "my-broker"
authenticationEnabled: false
authorizationEnabled: false
port: 1883
Unauthorized publish in MQTT 3.1.1
With MQTT 3.1.1, when a publish is denied, the client receives the PUBACK with no error because the protocol version doesn't support returning error code. MQTTv5 return PUBACK with reason code 135 (Not authorized) when publish is denied.