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-operations/manage-mqtt-broker/howto-configure-authentication.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ To link a BrokerListener to a *BrokerAuthentication* resource, specify the `auth
28
28
29
29
## Default BrokerAuthentication resource
30
30
31
-
Azure IoT Operations deploys a default *BrokerAuthentication* resource named `default` linked with the *default* listener in the `azure-iot-operations` namespace. It's configured to only use Kubernetes Service Account Tokens (SATs) for authentication.
31
+
Azure IoT Operations deploys a default *BrokerAuthentication* resource named `default` linked with the *default* listener in the `azure-iot-operations` namespace. It's configured to only use [Kubernetes Service Account Tokens (SATs)](#kubernetes-service-account-tokens) for authentication.
32
32
33
33
> [!IMPORTANT]
34
34
> The service account token (SAT) authentication method in the default *BrokerAuthentication* resource is required for components in the Azure IoT Operations to function correctly. Avoid updating or deleting the default *BrokerAuthentication* resource.
# Secure MQTT broker communication using BrokerListener
17
17
18
-
To customize the network access and security use the BrokerListener resource. A listener corresponds to a network endpoint that exposes the broker to the network. You can have one or more BrokerListener resources for each *Broker* resource, and thus multiple ports with different access control each.
18
+
To customize the network access and security use the BrokerListener resource. A listener corresponds to a network endpoint that exposes the broker to the network. You can have one or more BrokerListener resources for each Broker, and thus multiple ports with different access control each.
19
19
20
20
Each listener port can have its own authentication and authorization rules that define who can connect to the listener and what actions they can perform on the broker. You can use [BrokerAuthentication](./howto-configure-authentication.md) and [BrokerAuthorization](./howto-configure-authorization.md) resources to specify the access control policies for each listener. This flexibility allows you to fine-tune the permissions and roles of your MQTT clients, based on their needs and use cases.
21
21
@@ -35,7 +35,7 @@ For a list of all available settings, see the [Broker Listener API reference](/r
35
35
36
36
## Default BrokerListener
37
37
38
-
When you deploy Azure IoT Operations, the deployment also creates a BrokerListener resource named `default`. This listener is used to for encrypted internal communication between Azure IoT Operations components. The default listener is part of the [default *Broker*](./overview-broker.md#default-broker-resource), exposes a [ClusterIp service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip) on port 18883, uses [Kubernetes service account authentication](./howto-configure-authentication.md#enable-service-account-token-sat-authentication), has an [automatically managed](#configure-tls-with-automatic-certificate-management) TLS certificate, and doesn't use any authorization.
38
+
When you deploy Azure IoT Operations, the deployment also creates a BrokerListener resource named `default`. This listener is used to for encrypted internal communication between Azure IoT Operations components. The default listener is part of the [default Broker](./overview-broker.md#default-broker-resource), exposes a [ClusterIp service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip) on port 18883, uses [Kubernetes service account authentication](./howto-configure-authentication.md#default-brokerauthentication-resource), has an [automatically managed](#configure-tls-with-automatic-certificate-management) TLS certificate, and doesn't use any authorization.
39
39
40
40
> [!CAUTION]
41
41
> To avoid disrupting internal Azure IoT Operations communication, keep the default listener unchanged and dedicated for internal use. For external communication, [create a new listener](#create-new-broker-listeners). If you need to use the ClusterIp service, add more ports to the default listener without changing any of the existing settings.
@@ -186,6 +186,8 @@ To create a new listener, specify the following settings:
186
186
- **Ports**: List of ports that to listen on. See [Ports](#ports).
187
187
- (Optional) **Service name**: override the Kubernetes service name. See [Service name](#service-name).
188
188
189
+
### Example: Create a new listener with two ports
190
+
189
191
This example shows how to create a new listener with load balancer service type. The BrokerListener resource defines a two ports that accept MQTT connections from clients.
190
192
191
193
- The first port listens on port 1883 without TLS and authentication. Clients can connect to the broker without encryption or authentication. This setup is suitable for testing only. [Don't use this configuration in production](./howto-test-connection.md#only-turn-off-tls-and-authentication-for-testing).
@@ -372,12 +374,12 @@ To enable TLS with automatic certificate management, specify the TLS settings on
372
374
373
375
### Verify cert-manager installation
374
376
375
-
With automatic certificate management, you use cert-manager to manage the TLS server certificate. By default, cert-manager is installed alongside Azure IoT Operations Preview in the `azure-iot-operations` namespace already. Verify the installation before proceeding.
377
+
With automatic certificate management, you use cert-manager to manage the TLS server certificate. By default, cert-manager is installed alongside Azure IoT Operations Preview in the `cert-manager` namespace already. Verify the installation before proceeding.
376
378
377
379
1. Use `kubectl` to check for the pods matching the cert-manager app labels.
378
380
379
381
```bash
380
-
kubectl get pods --namespace azure-iot-operations -l 'app in (cert-manager,cainjector,webhook)'
382
+
kubectl get pods --namespace cert-manager -l 'app in (cert-manager,cainjector,webhook)'
381
383
```
382
384
383
385
```Output
@@ -390,7 +392,7 @@ With automatic certificate management, you use cert-manager to manage the TLS se
390
392
1. If you see the pods shown as ready and running, cert-manager is installed and ready to use.
391
393
392
394
> [!TIP]
393
-
> To further verify the installation, check the cert-manager documentation [verify installation](https://cert-manager.io/docs/installation/kubernetes/#verifying-the-installation). Remember to use the `azure-iot-operations` namespace.
395
+
> To further verify the installation, check the cert-manager documentation [verify installation](https://cert-manager.io/docs/installation/kubernetes/#verifying-the-installation). Remember to use the `cert-manager` namespace.
394
396
395
397
### Create an Issuer for the TLS server certificate
396
398
@@ -539,7 +541,8 @@ The following is an example of a BrokerListener resource that enables TLS on por
@@ -611,61 +615,6 @@ Deploy the Bicep file using Azure CLI.
611
615
az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep
612
616
```
613
617
614
-
#### Optional: Configure server certificate parameters
615
-
616
-
The only required parameters are `issuerRef.name` and `issuerRef.kind`. All properties of the generated TLS server certificates are automatically chosen. However, MQTT broker allows certain properties to be customized by specifying them in the BrokerListener resource, under `tls.automatic.issuerRef`. The following is an example of all supported properties:
617
-
618
-
```bicep
619
-
ports: [
620
-
{
621
-
port: 8884
622
-
tls: {
623
-
mode: 'Automatic'
624
-
certManagerCertificateSpec: {
625
-
issuerRef: {
626
-
// Name of issuer. Required.
627
-
name: 'my-issuer'
628
-
// 'Issuer' or 'ClusterIssuer'. Required.
629
-
kind: 'Issuer'
630
-
// Issuer group. Optional; defaults to 'cert-manager.io'.
631
-
// External issuers may use other groups.
632
-
group: 'cert-manager.io'
633
-
}
634
-
// Namespace of certificate. Optional; omit to use default namespace.
635
-
namespace: 'az'
636
-
// Where to store the generated TLS server certificate. Any existing
637
-
// data at the provided secret will be overwritten.
638
-
// Optional; defaults to 'my-issuer-{port}'.
639
-
secret: 'my-issuer-8884'
640
-
// Parameters for the server certificate's private key.
641
-
// Optional; defaults to rotationPolicy: Always, algorithm: ECDSA, size: 256.
642
-
privateKey: {
643
-
rotationPolicy: 'Always'
644
-
algorithm: 'ECDSA'
645
-
size: 256
646
-
}
647
-
// Total lifetime of the TLS server certificate. Optional; defaults to '720h' (30 days).
648
-
duration: '720h'
649
-
// When to begin renewing the certificate. Optional; defaults to '240h' (10 days).
650
-
renewBefore: '240h'
651
-
// Any additional SANs to add to the server certificate. Omit if not required.
652
-
san: {
653
-
dns: [
654
-
'iotmq.example.com'
655
-
// To connect to the broker from a different namespace, add the following DNS name:
name: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'
678
627
namespace: azure-iot-operations
679
628
spec:
680
629
brokerRef: default
681
630
serviceType: loadBalancer
682
-
serviceName: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'
683
631
ports:
684
632
- port: 8884 # Avoid conflicts with default port 18883
685
633
tls:
@@ -690,60 +638,26 @@ spec:
690
638
kind: Issuer
691
639
```
692
640
641
+
---
642
+
693
643
Once the BrokerListener resource is configured, MQTT broker automatically creates a new service with the specified port and TLS enabled.
694
644
695
645
#### Optional: Configure server certificate parameters
696
646
697
-
The only required parameters are `issuerRef.name` and `issuerRef.kind`. All properties of the generated TLS server certificates are automatically chosen. However, MQTT broker allows certain properties to be customized by specifying them in the BrokerListener resource, under `tls.automatic.issuerRef`. The following is an example of all supported properties:
647
+
The only required parameters are issuer name and issuer kind. All properties of the generated TLS server certificates are automatically chosen. However, MQTT broker allows certain properties to be customized following the same syntax as cert-manager Certificates. For example, you can specify the private key algorithm and rotation policy. These settings are under `tls.certManagerCertificateSpec` or the **TLS configuration** pane in the Azure portal.
698
648
699
-
```yaml
700
-
# cert-manager issuer for TLS server certificate. Required.
701
-
issuerRef:
702
-
# Name of issuer. Required.
703
-
name: my-issuer
704
-
# 'Issuer' or 'ClusterIssuer'. Required.
705
-
kind: Issuer
706
-
# Issuer group. Optional; defaults to 'cert-manager.io'.
707
-
# External issuers may use other groups.
708
-
group: cert-manager.io
709
-
# Namespace of certificate. Optional; omit to use default namespace.
710
-
namespace: az
711
-
# Where to store the generated TLS server certificate. Any existing
712
-
# data at the provided secret will be overwritten.
713
-
# Optional; defaults to 'my-issuer-{port}'.
714
-
secret: my-issuer-8884
715
-
# Parameters for the server certificate's private key.
716
-
# Optional; defaults to rotationPolicy: Always, algorithm: ECDSA, size: 256.
717
-
privateKey:
718
-
rotationPolicy: Always
719
-
algorithm: ECDSA
720
-
size: 256
721
-
# Total lifetime of the TLS server certificate. Optional; defaults to '720h' (30 days).
722
-
duration: 720h
723
-
# When to begin renewing the certificate. Optional; defaults to '240h' (10 days).
724
-
renewBefore: 240h
725
-
# Any additional SANs to add to the server certificate. Omit if not required.
726
-
san:
727
-
dns:
728
-
- iotmq.example.com
729
-
# To connect to the broker from a different namespace, add the following DNS name:
For a full list of these settings, see [Broker Listener CertManagerCertificateSpec API reference](/rest/api/iotoperationsmq/broker-listener/create-or-update#certmanagercertificatespec).
734
650
735
651
#### Verify deployment
736
652
737
-
Use kubectl to check that the service associated with the BrokerListener resource is running. From the example above, the service name is `my-new-tls-listener` and the namespace is `azure-iot-operations`. The following command checks the service status:
653
+
Use kubectl to check that the service associated with the BrokerListener resource is running. From the example above, the service name is `aio-broker-loadbalancer-tls` and the namespace is `azure-iot-operations`. The following command checks the service status:
738
654
739
655
```console
740
656
$ kubectl get service my-new-tls-listener -n azure-iot-operations
Once the server certificate is configured, TLS is enabled. To test with mosquitto:
@@ -767,7 +681,6 @@ To help you get started, Azure IoT Operations is deployed with a default "quicks
767
681
768
682
For production, you must configure a CA issuer with a certificate from a trusted CA, as described in the previous sections.
769
683
770
-
771
684
## Configure TLS with manual certificate management
772
685
773
686
To manually configure MQTT broker to use a specific TLS certificate, specify it in a BrokerListener resource with a reference to a Kubernetes secret. Then deploy it using kubectl. This article shows an example to configure TLS with self-signed certificates for testing.
@@ -833,7 +746,7 @@ The following is an example of a BrokerListener resource that enables TLS on por
833
746
834
747
1. In the Azure portal, navigate to your IoT Operations instance.
835
748
1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
836
-
1. Select or create a listener. You can only create one listener per service type. If you already have a listener of the same service type, you can add more ports to the existing listener.
749
+
1. Select or create a listener. You can only create one listener per service type. If you already have a listener of the same service type, you can add more ports to the existing listener. To follow the example, specify the listener service name as `mqtts-endpoint`.
837
750
1. You can add TLS settings to the listener by selecting the **TLS** on an existing port or by adding a new port.
838
751
839
752
:::image type="content" source="media/howto-configure-brokerlistener/tls-manual.png" alt-text="Screenshot using Azure portal to create MQTT broker for load balancer listener with manual TLS certificates." lightbox="media/howto-configure-brokerlistener/tls-manual.png":::
@@ -852,11 +765,13 @@ The following is an example of a BrokerListener resource that enables TLS on por
852
765
853
766
# [Bicep](#tab/bicep)
854
767
768
+
Modify the `tls` setting in a BrokerListener resource to specify manual TLS configuration referencing the Kubernetes secret. Note the name of the secret used for the TLS server certificate (`server-cert-secret` in the example previously).
0 commit comments