Skip to content

Commit 06b61f3

Browse files
PatAltimorePatAltimore
committed
Brokerlistener changes
1 parent 0f4288e commit 06b61f3

File tree

2 files changed

+59
-31
lines changed

2 files changed

+59
-31
lines changed

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

Lines changed: 16 additions & 10 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: 07/26/2024
10+
ms.date: 07/27/2024
1111

1212
#CustomerIntent: As an operator, I want to configure authentication so that I have secure MQTT broker communications.
1313
---
@@ -38,8 +38,10 @@ spec:
3838
listenerRef:
3939
- listener
4040
authenticationMethods:
41-
- sat:
42-
audiences: ["aio-mq"]
41+
- method: ServiceAccountToken
42+
serviceAccountToken:
43+
audiences:
44+
- aio-mq
4345
```
4446
4547
To change the configuration, modify the `authenticationMethods` setting in this BrokerAuthentication resource or create new brand new BrokerAuthentication resource with a different name. Then, deploy it using `kubectl apply`.
@@ -80,9 +82,11 @@ spec:
8082
listenerRef:
8183
- listener
8284
authenticationMethods:
83-
- custom:
85+
- method: custom
86+
# ...
87+
- method: serviceAccountToken
8488
# ...
85-
- sat:
89+
- method: x509Credentials
8690
# ...
8791
```
8892

@@ -162,7 +166,7 @@ metadata:
162166
namespace: azure-iot-operations
163167
spec:
164168
authenticationMethods:
165-
- x509Credentials:
169+
- method: x509Credentials
166170
authorizationAttributes:
167171
root:
168172
subject = "CN = Contoso Root CA Cert, OU = Engineering, C = US"
@@ -192,7 +196,7 @@ Finally, once the trusted client root CA certificate and the certificate-to-attr
192196
```yaml
193197
spec:
194198
authenticationMethods:
195-
- x509:
199+
- method: x509Credentials
196200
trustedClientCaCert: client-ca
197201
attributes:
198202
secretName: x509-attributes
@@ -264,13 +268,15 @@ Clients authentication via SAT can optionally have their SATs annotated with att
264268

265269
### Enable Service Account Token (SAT) authentication
266270

267-
Modify the `authenticationMethods` setting in a BrokerAuthentication resource to specify `sat` as a valid authentication method. The `audiences` specifies the list of valid audiences for tokens. Choose unique values that identify the MQTT broker service. You must specify at least one audience, and all SATs must match one of the specified audiences.
271+
Modify the `authenticationMethods` setting in a BrokerAuthentication resource to specify `ServiceAccountToken` as a valid authentication method. The `audiences` specifies the list of valid audiences for tokens. Choose unique values that identify the MQTT broker service. You must specify at least one audience, and all SATs must match one of the specified audiences.
268272

269273
```yaml
270274
spec:
271275
authenticationMethods:
272-
- sat:
273-
audiences: ["aio-mq", "my-audience"]
276+
- method: ServiceAccountToken
277+
audiences:
278+
- aio-mq
279+
- my-audience
274280
```
275281

276282
Apply your changes with `kubectl apply`. It might take a few minutes for the changes to take effect.

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

Lines changed: 43 additions & 21 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: 07/02/2024
10+
ms.date: 07/27/2024
1111

1212
#CustomerIntent: As an operator, I want understand options to secure MQTT communications for my IoT Operations solution.
1313
---
@@ -23,15 +23,35 @@ Each listener can have its own authentication and authorization rules that defin
2323
The *BrokerListener* resource has these fields:
2424

2525
| Field Name | Required | Description |
26-
| --- | --- | --- |
27-
| `brokerRef` | Yes | The name of the broker resource that this listener belongs to. This field is required and must match an existing *Broker* resource in the same namespace. |
28-
| `port` | Yes | The port number that this listener listens on. This field is required and must be a valid TCP port number. |
29-
| `serviceType` | No | The type of the Kubernetes service created for this listener. This subfield is optional and defaults to `clusterIp`. Must be either `loadBalancer`, `clusterIp`, or `nodePort`. |
30-
| `serviceName` | No | The name of Kubernetes service created for this listener. Kubernetes creates DNS records for this `serviceName` that clients should use to connect to MQTT broker. This subfield is optional and defaults to `aio-mq-dmqtt-frontend`. Important: If you have multiple listeners with the same `serviceType` and `serviceName`, the listeners share the same Kubernetes service. For more information, see [Service name and service type](#service-name-and-service-type). |
31-
| `authenticationEnabled` | No | A boolean flag that indicates whether this listener requires authentication from clients. If set to `true`, this listener uses any *BrokerAuthentication* resources associated with it to verify and authenticate the clients. If set to `false`, this listener allows any client to connect without authentication. This field is optional and defaults to `false`. To learn more about authentication, see [Configure MQTT broker authentication](howto-configure-authentication.md). |
32-
| `authorizationEnabled` | No | A boolean flag that indicates whether this listener requires authorization from clients. If set to `true`, this listener uses any *BrokerAuthorization* resources associated with it to verify and authorize the clients. If set to `false`, this listener allows any client to connect without authorization. This field is optional and defaults to `false`. To learn more about authorization, see [Configure MQTT broker authorization](howto-configure-authorization.md). |
33-
| `tls` | No | The TLS settings for the listener. The field is optional and can be omitted to disable TLS for the listener. To configure TLS, set it one of these types: <br> * If set to `automatic`, this listener uses cert-manager to get and renew a certificate for the listener. To use this type, [specify an `issuerRef` field to reference the cert-manager issuer](howto-configure-tls-auto.md). <br> * If set to `manual`, the listener uses a manually provided certificate for the listener. To use this type, [specify a `secretName` field that references a Kubernetes secret containing the certificate and private key](howto-configure-tls-manual.md). |
34-
| `protocol` | No | The protocol that this listener uses. This field is optional and defaults to `mqtt`. Must be either `mqtt` or `websockets`. |
26+
|------------|----------|-------------|
27+
| brokerRef | Yes | The name of the broker resource that this listener belongs to. This field is required and must match an existing *Broker* resource in the same namespace. |
28+
| ports[] | Yes | The listener can listen on multiple ports. List of ports that the listener accepts client connections. |
29+
| ports.authenticationRef | No | Reference to client authentication settings. Omit to disable authentication. To learn more about authentication, see [Configure MQTT broker authentication](howto-configure-authentication.md). |
30+
| ports.authorizationRef | No | Reference to client authorization settings. Omit to disable authorization. |
31+
| ports.nodePort | No | Kubernetes node port. Only relevant when this port is associated with a NodePort listener. |
32+
| ports.port | Yes | TCP port for accepting client connections. |
33+
| ports.protocol | No | Protocol to use for client connections. Values: `Mqtt`, `Websockets`. Default: `Mqtt` |
34+
| ports.tls | No | TLS server certificate settings for this port. Omit to disable TLS. |
35+
| ports.tls.automatic | No | Automatic TLS server certificate management with cert-manager. [Configure TLS with automatic certificate management](howto-configure-tls-auto.md)|
36+
| ports.tls.automatic.duration | No | Lifetime of certificate. Must be specified using a *Go* time format (h\|m\|s). For example, 240h for 240 hours and 45m for 45 minutes. |
37+
| ports.tls.automatic.issuerRef | No | cert-manager issuer reference. |
38+
| ports.tls.automatic.issuerRef.group | No | cert-manager issuer group. |
39+
| ports.tls.automatic.issuerRef.kind | No | cert-manager issuer kind. Values: `Issuer`, `ClusterIssuer`. |
40+
| ports.tls.automatic.issuerRef.name | No | cert-manager issuer name. |
41+
| ports.tls.automatic.privateKey | No | Type of certificate private key. |
42+
| ports.tls.automatic.privateKey.algorithm | No | Algorithm for the private key. Values: `Ec256`, `Ec384`, `ec521`, `Ed25519`, `Rsa2048`, `Rsa4096`, `Rsa8192`. |
43+
| ports.tls.automatic.privateKey.rotationPolicy | No | Size of the private key. Values: `Always`, `Never`. |
44+
| ports.tls.automatic.renewBefore | No | When to begin certificate renewal. Must be specified using a *Go* time format (h\|m\|s). For example, 240h for 240 hours and 45m for 45 minutes. |
45+
| ports.tls.automatic.san | No | Additional Subject Alternative Names (SANs) to include in the certificate. |
46+
| ports.tls.automatic.san.dns | No | DNS SANs. |
47+
| ports.tls.automatic.san.ip | No | IP address SANs. |
48+
| ports.tls.automatic.secretName | No | Secret for storing server certificate. Any existing data will be overwritten. This is a reference to the secret through an identifying name, not the secret itself. |
49+
| ports.tls.automatic.secretNamespace | No | Certificate Kubernetes namespace. Omit to use current namespace. |
50+
| ports.tls.manual | No | Manual TLS server certificate management through a defined secret. For more information, see [Configure TLS with manual certificate management](howto-configure-tls-manual.md).|
51+
| ports.tls.manual.secretName | Yes | Kubernetes secret containing an X.509 client certificate. This is a reference to the secret through an identifying name, not the secret itself. |
52+
| ports.tls.manual.secretNamespace | No | Certificate K8S namespace. Omit to use current namespace. |
53+
| serviceName | No | The name of Kubernetes service created for this listener. Kubernetes creates DNS records for this `serviceName` that clients should use to connect to MQTT broker. This subfield is optional and defaults to `aio-mq-dmqtt-frontend`. Important: If you have multiple listeners with the same `serviceType` and `serviceName`, the listeners share the same Kubernetes service. For more information, see [Service name and service type](#service-name-and-service-type). |
54+
| serviceType | No | The type of the Kubernetes service created for this listener. This subfield is optional and defaults to `clusterIp`. Must be either `loadBalancer`, `clusterIp`, or `nodePort`. |
3555

3656
## Default BrokerListener
3757

@@ -53,17 +73,19 @@ metadata:
5373
namespace: azure-iot-operations
5474
spec:
5575
brokerRef: broker
56-
authenticationEnabled: true
57-
authorizationEnabled: false
58-
port: 8883
59-
serviceName: aio-mq-dmqtt-frontend
60-
serviceType: clusterIp
61-
tls:
62-
automatic:
63-
issuerRef:
64-
group: cert-manager.io
65-
kind: Issuer
66-
name: mq-dmqtt-frontend
76+
ports:
77+
- authenticationRef: authn
78+
port: 8883
79+
protocol: Mqtt
80+
tls:
81+
automatic:
82+
issuerRef:
83+
apiGroup: cert-manager.io
84+
kind: Issuer
85+
name: mq-dmqtt-frontend
86+
mode: Automatic
87+
serviceName: aio-mq-dmqtt-frontend
88+
serviceType: ClusterIp
6789
```
6890
6991
To learn more about the default BrokerAuthentication resource linked to this listener, see [Default BrokerAuthentication resource](howto-configure-authentication.md#default-brokerauthentication-resource).

0 commit comments

Comments
 (0)