Sécuriser la communication de l’Agent MQTT à l’aide de BrokerListener

Article
11/21/2024

Important

Cette page inclut des instructions pour la gestion des composants Azure IoT Operations à l’aide des manifestes de déploiement Kubernetes, qui sont en version préliminaire. Cette fonctionnalité est fournie avec plusieurs limitations et ne doit pas être utilisée pour les charges de travail de production.

Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.

Un BrokerListener correspond à un point de terminaison réseau qui expose le répartiteur aux clients sur le réseau. Vous pouvez disposer d’une ou de plusieurs ressources BrokerListener pour chaque répartiteur, avec plusieurs ports et un contrôle d’accès différent sur chacun d’eux.

Chaque port BrokerListener peut avoir ses propres règles d’authentification et d’autorisation qui définissent qui peut se connecter sur ce port d’écouteur et quelles actions il peut effectuer sur le répartiteur. Vous pouvez utiliser les ressources BrokerAuthentication et BrokerAuthorization pour spécifier les stratégies de contrôle d’accès pour chaque port d’écouteur. Cette flexibilité vous permet d’affiner les autorisations et les rôles de vos clients MQTT en fonction de leurs besoins et de leurs cas d’usage.

Conseil

Le déploiement de l’Agent MQTT par défaut est un service IP de cluster qui nécessite que les clients se connectent avec le protocole TLS et s’authentifient avec des jetons de compte de service. Les clients se connectant depuis l’extérieur du cluster ont besoin d’une configuration supplémentaire pour pouvoir se connecter.

Les écouteurs de répartiteur présentent les caractéristiques suivantes :

Nom : nom de l’écouteur. Ce nom est également le nom du service Kubernetes, sauf substitution.
Type de service : vous pouvez avoir jusqu’à trois écouteurs, un par type de service. L’écouteur par défaut est le type de service ClusterIp.
Ports : chaque écouteur prend en charge plusieurs ports. Les ports ne peuvent pas entrer en conflit sur différents écouteurs.
Références d’authentification et d’autorisation : BrokerAuthentication et BrokerAuthorization sont configurés par port.
TLS : la configuration TLS manuelle ou automatique est appliquée par port.
Protocole : MQTT sur WebSockets peut être activé par port.

Pour obtenir la liste des paramètres disponibles, consultez les Informations de référence sur l’API Broker Listener.

BrokerListener par défaut

Lorsque vous déployez Opérations Azure IoT, le déploiement crée également une ressource BrokerListener nommée default. Cet écouteur est utilisé pour la communication interne chiffrée entre les composants des Opérations Azure IoT. L’écouteur par défaut fait partie du répartiteur par défaut.

Il expose un service ClusterIp sur le port 18883
Les clients doivent utiliser l’authentification de compte de service Kubernetes
Il a un certificat TLS géré automatiquement
Il ne configure aucune stratégie d’autorisation client

Attention

Pour éviter de perturber la communication interne des Opérations Azure IoT, conservez l’écouteur par défaut inchangé et dédié pour une utilisation interne. Pour la communication externe, créez un écouteur. Si vous devez utiliser le service ClusterIp, ajoutez d’autres ports à l’écouteur par défaut sans modifier les paramètres existants.

Pour afficher ou modifier l’écouteur par défaut :

Dans le portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Dans la liste des écouteurs du broker, sélectionnez l’écouteur par défaut.
Passez en revue les paramètres de l’écouteur, mais évitez de modifier les paramètres existants. Au lieu de cela, créez un port et configurez-le en fonction des besoins.

Soyez prudent lors de la modification de l’écouteur par défaut à l’aide de Bicep. Ne modifiez pas les paramètres existants. Ajoutez plutôt d’autres ports à l’écouteur par défaut. L’exemple suivant montre comment ajouter un port à l’écouteur par défaut.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource defaultListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    // Don't change the service name or service type
    serviceType: 'ClusterIp'
    serviceName: 'aio-broker'
    ports: [
      // Don't modify the default port 18883 settings
      {
        port: 18883
        authenticationRef: 'default'
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
            privateKey: {
              algorithm: 'Ec256'
              rotationPolicy: 'Always'
            }
          }
        }
      }
      // Add more ports here, like the following example
      {
        port: 1884
        protocol: 'Mqtt'
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Pour afficher la ressource BrokerListener par défaut, utilisez la commande suivante :

kubectl get brokerlistener default -n azure-iot-operations -o yaml

La sortie devrait ressembler à ceci, la majorité des métadonnées ayant été supprimées par souci de concision :

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: default
  namespace: azure-iot-operations
  ownerReferences:
  - apiVersion: mqttbroker.iotoperations.azure.com/v1
    kind: Broker
    name: default
spec:
  serviceType: ClusterIp
  serviceName: aio-broker
  ports:
  - port: 18883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: azure-iot-operations-aio-certificate-issuer
          kind: ClusterIssuer
          group: cert-manager.io
        privateKey:
          algorithm: Ec256
          rotationPolicy: Always

Pour ajouter un nouveau port 1883 sans TLS et avec authentification désactivée à l’écouteur par défaut, utilisez la commande kubectl patch :

kubectl patch brokerlistener default -n azure-iot-operations --type='json' -p='[{"op": "add", "path": "/spec/ports/-", "value": {"port": 1883, "protocol": "Mqtt"}}]'

Éviter de modifier l’écouteur de répartiteur par défaut

Étant donné que l’écouteur de répartiteur par défaut utilise le type de service ClusterIp et que vous ne pouvez avoir qu’un seul écouteur par type de service, ajoutez d’autres ports à l’écouteur par défaut sans modifier les paramètres existants si vous devez utiliser le service ClusterIp.

Créer des écouteurs de broker

Pour créer un écouteur, spécifiez les paramètres suivants :

Nom : nom de l’écouteur. Ce nom est également le nom du service Kubernetes, sauf substitution.
Type de service : type du service Kubernetes. Consultez Type de service.
Ports : liste des ports à écouter. Consultez Ports.
(Facultatif) Nom du service : remplacez le nom du service Kubernetes. Consultez Nom du service.

Exemple : Créer un écouteur avec deux ports

Cet exemple montre comment créer un écouteur avec un type de service d’équilibreur de charge. La ressource BrokerListener définit deux ports qui acceptent les connexions MQTT venant des clients.

Le premier port écoute sur le port 1883 sans TLS ni authentification. Cette configuration convient uniquement aux tests. N’utilisez pas cette configuration en production.
Le second port écoute sur le port 8883 avec TLS et authentification activés. Seuls les clients authentifiés avec un jeton de compte de service Kubernetes peuvent se connecter. Le protocole TLS est défini sur le mode automatique, à l’aide de cert-manager pour gérer le certificat de serveur à partir de l’émetteur par défaut. Cette configuration est plus proche d’une configuration de production.

Dans le portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.

Sélectionnez Écouteur de l’Agent MQTT pour LoadBalancer>Créer.

Entrez les paramètres suivants :

Setting	Description
Nom	Nom de la ressource BrokerListener.
Nom du service	Nom du service Kubernetes. Laissez-le vide pour utiliser le nom de l’écouteur en tant que nom de service.
Type de service	LoadBalancer déjà sélectionné.

Sous Ports, entrez les paramètres suivants pour le premier port :

Setting Description

Port Entrez 1883

Authentification Choisissez Aucun(e)

Autorisation Choisissez Aucun(e)

Protocol Choisir MQTT

TLS Ne pas ajouter
Sélectionnez Ajouter une entrée de port pour ajouter un deuxième port et entrez les paramètres suivants :

Setting Description

Port Entrez 8883

Authentification Choose par défaut

Autorisation Choisissez Aucun(e)

Protocol Choisir MQTT

TLS Sélectionnez Ajouter
Dans le volet Configuration TLS, entrez les paramètres suivants :

Setting Description

Mode TLS Choisissez Automatique

Nom de l'émetteur Entrez azure-iot-operations-aio-certificate-issuer

Type d’émetteur Choisissez ClusterIssuer

Conservez les valeurs par défaut pour les autres paramètres, puis sélectionnez Appliquer.
Sélectionnez Créer un écouteur.

Setting	Description
Port	Entrez 1883
Authentification	Choisissez Aucun(e)
Autorisation	Choisissez Aucun(e)
Protocol	Choisir MQTT
TLS	Ne pas ajouter

Setting	Description
Port	Entrez 8883
Authentification	Choose par défaut
Autorisation	Choisissez Aucun(e)
Protocol	Choisir MQTT
TLS	Sélectionnez Ajouter

Setting	Description
Mode TLS	Choisissez Automatique
Nom de l'émetteur	Entrez `azure-iot-operations-aio-certificate-issuer`
Type d’émetteur	Choisissez ClusterIssuer

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = '<LISTENER_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        port: 1883
        protocol: 'Mqtt'
      }
      {
        authenticationRef: 'default'
        port: 8883
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: <LISTENER_NAME>
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: LoadBalancer
  ports:
  - port: 1883
    protocol: Mqtt
  - port: 8883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
            name: azure-iot-operations-aio-certificate-issuer
            kind: ClusterIssuer
            group: cert-manager.io

Type de service

Chaque BrokerListener est mappé à un service Kubernetes. Le type de service détermine la façon dont le répartiteur est exposé au réseau. Les types de service pris en charge sont les suivants :

ClusterIp : expose le répartiteur sur une adresse IP interne de cluster. Les clients peuvent se connecter au répartiteur à partir du cluster. Il s’agit du type de service par défaut de l’écouteur par défaut.
NodePort : expose le répartiteur sur l’adresse IP de chaque nœud à un port statique. Les clients peuvent se connecter au répartiteur à partir de l’extérieur du cluster. Ce type de service est utile pour le développement et les tests.
LoadBalancer : expose le répartiteur en externe. Le service reçoit une adresse IP externe que les clients peuvent utiliser pour se connecter au répartiteur. Il s’agit du type de service le plus courant pour les déploiements de production.

Un seul écouteur par type de service

Un seul écouteur par type de service est autorisé. Si vous avez besoin d’une connectivité supplémentaire du même type de service, ajoutez d’autres ports à l’écouteur existant de ce type de service.

Nom du service

Le nom du service est le nom du service Kubernetes associé au répartiteur. S’il n’est pas spécifié, le nom de l’écouteur de répartiteur est utilisé comme nom de service. Le nom du service doit être unique dans l’espace de noms.

Conseil

Pour éviter une surcharge de gestion, nous vous recommandons de laisser le nom du service vide. Le nom de l’écouteur est unique et peut être utilisé pour identifier le service. Utilisez le nom du service comme remplacement uniquement lorsque vous ne pouvez pas nommer le service d’après l’écouteur.

Ports

Chaque écouteur peut avoir plusieurs ports, et chaque port peut avoir ses propres paramètres pour l’authentification, l’autorisation, le protocole et TLS.

Pour utiliser votre propre paramètre d’authentification ou d’autorisation pour un port, vous devez créer les ressources correspondantes avant de l’utiliser avec un écouteur. Pour plus d’informations, consultez Configurer l’authentification de l’Agent MQTT et Configurer l’autorisation de l’Agent MQTT.

Pour utiliser le protocole TLS, consultez les sections Configurer le protocole TLS avec la gestion automatique des certificats ou Configurer le protocole TLS avec la gestion manuelle des certificats.

Utilisation du même port sur plusieurs écouteurs

L’utilisation du même numéro de port sur différents écouteurs n’est pas prise en charge. Chaque numéro de port doit être unique dans l’Agent MQTT des Opérations Azure IoT.

Par exemple, si vous avez un écouteur sur le port 1883, vous ne pouvez pas créer un autre écouteur avec le port 1883. De même, l’écouteur par défaut utilise le port 18883. Vous ne pouvez donc pas créer un autre écouteur avec le port 18883.

Prise en charge des WebSockets

L’Agent MQTT des Opérations Azure IoT prend en charge MQTT sur WebSockets. Pour activer WebSockets, définissez le protocole sur WebSockets pour le port.

Configurer TLS avec la gestion automatique des certificats

Pour activer TLS avec la gestion automatique des certificats, spécifiez les paramètres TLS sur un port d’écouteur.

Vérifier l’installation du gestionnaire de certificats

Avec la gestion automatique des certificats, vous utilisez le gestionnaire de certificats pour gérer le certificat de serveur TLS. Par défaut, le gestionnaire de certificats est déjà installé en même temps que les Opérations Azure IoT dans l’espace de noms cert-manager. Vérifiez l’installation avant de continuer.

Utilisez kubectl pour rechercher les pods correspondant aux étiquettes d’application du gestionnaire de certificats.

kubectl get pods --namespace cert-manager -l 'app in (cert-manager,cainjector,webhook)'

NAME                                           READY   STATUS    RESTARTS       AGE
aio-cert-manager-64f9548744-5fwdd              1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-cainjector-6c7c546578-p6vgv   1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-webhook-7f676965dd-8xs28      1/1     Running   4 (145m ago)   4d20h

Si vous voyez les pods affichés comme prêts et en cours d’exécution, le gestionnaire de certificats est installé et prêt à être utilisé.

Conseil

Pour vérifier davantage l’installation, consultez la documentation du gestionnaire de certificats vérifier l’installation. N’oubliez pas d’utiliser l’espace de noms cert-manager.

Créer un émetteur pour le certificat de serveur TLS

La ressource Émetteur du gestionnaire de certificats définit la façon dont les certificats sont émis automatiquement. Cert-manager prend en charge plusieurs types d’émetteurs en mode natif. Il prend également en charge un type d’émetteur externe pour étendre les fonctionnalités au-delà des émetteurs pris en charge en mode natif. Vous pouvez utiliser l’agent MQTT avec n’importe quel type d’émetteur de gestionnaire de certificats.

Important

Pendant le déploiement initial, Opérations Azure IoT est installé avec un émetteur par défaut pour les certificats de serveur TLS. Vous pouvez utiliser cet émetteur pour le développement et le test. Pour plus d’informations, consultez autorité de certification racine et émetteur par défaut avec Opérations Azure IoT. Les étapes ci-dessous ne sont requises que si vous souhaitez utiliser un autre émetteur.

L’approche de création de l’émetteur est différente en fonction de votre scénario. Les sections suivantes répertorient des exemples pour vous aider à commencer.

Développement ou test
Production

L’émetteur de l’autorité de certification est utile pour le développement et le test. Il doit être configuré avec un certificat et une clé privée stockés dans un secret Kubernetes.

Configurer le certificat racine en tant que secret Kubernetes

Si vous disposez d’un certificat d’autorité de certification existant, créez un secret Kubernetes avec le certificat d’autorité de certification et les fichiers PEM de clé privée d’autorité de certification. Exécutez la commande suivante pour importer le certificat d’autorité de certification en tant que secret Kubernetes et ignorez la section suivante.

kubectl create secret tls test-ca --cert tls.crt --key tls.key -n azure-iot-operations

Si vous n’avez pas de certificat d’autorité de certification, cert-manager peut générer un certificat d’autorité de certification pour vous. L’utilisation de cert-manager pour générer un certificat d’autorité de certification racine est connue sous le nom de démarrage d’un émetteur d’autorité de certification à l’aide d’un certificat auto-signé.

Commencez par créer ca.yaml :

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-ca-issuer
  namespace: azure-iot-operations
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: selfsigned-ca-cert
  namespace: azure-iot-operations
spec:
  isCA: true
  commonName: test-ca
  secretName: test-ca
  issuerRef:
    # Must match Issuer name above
    name: selfsigned-ca-issuer
    # Must match Issuer kind above
    kind: Issuer
    group: cert-manager.io
  # Override default private key config to use an EC key
  privateKey:
    rotationPolicy: Always
    algorithm: ECDSA
    size: 256

Créez le certificat d’autorité de certification auto-signé avec la commande suivante :
```
kubectl apply -f ca.yaml
```

Le gestionnaire de certificats crée un certificat d’autorité de certification à l’aide de ses valeurs par défaut. Vous pouvez modifier les propriétés de ce certificat en modifiant la spécification du certificat. Consultez la documentation du gestionnaire de certificats pour obtenir la liste des options valides.

Distribuer le certificat racine

L’exemple précédent stocke le certificat d’autorité de certification dans un secret Kubernetes appelé test-ca. Le certificat au format PEM peut être récupéré à partir du secret et stocké dans un fichier ca.crt avec la commande suivante :

kubectl get secret test-ca -n azure-iot-operations -o json | jq -r '.data["tls.crt"]' | base64 -d > ca.crt

Ce certificat doit être distribué et approuvé par tous les clients. Par exemple, utilisez un indicateur --cafile pour un client mosquitto.

Créer un émetteur basé sur un certificat d’autorité de certification

Le gestionnaire de certificats a besoin d’un émetteur basé sur le certificat d’autorité de certification généré ou importé à l’étape précédente. Créez le fichier suivant en tant que issuer-ca.yaml :

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: my-issuer
  namespace: azure-iot-operations
spec:
  ca:
    # Must match secretName of generated or imported CA cert
    secretName: test-ca

Créez l’émetteur avec la commande suivante :

kubectl apply -f issuer-ca.yaml

La commande précédente crée un émetteur pour émettre les certificats de serveur TLS. Notez le nom et le type de l’émetteur. Dans l’exemple, le nom est my-issuer et le type est Issuer. Ces valeurs sont définies dans la ressource BrokerListener ultérieurement.

Pour la production, consultez la documentation de cert-manager pour voir l’émetteur qui vous convient le mieux. Par exemple, avec l’émetteur de coffre :

Déployez le coffre HashiCorp dans un environnement de choix, comme Kubernetes. Initialisez et ouvrez le coffre en conséquence.
Créez et configurez le moteur de secrets PKI en important votre certificat d’autorité de certification.
Configurez le coffre avec le rôle et la stratégie pour l’émission de certificats de serveur.

Voici un exemple de rôle. Notez que ExtKeyUsageServerAuth permet au certificat du serveur de fonctionner :
```
vault write pki/roles/my-issuer \
  allow_any_name=true \
  client_flag=false \
  ext_key_usage=ExtKeyUsageServerAuth \
  no_store=true \
  max_ttl=240h
```
Exemple de stratégie pour le rôle :
```
path "pki/sign/my-issuer" {
  capabilities = ["create", "update"]
}
```
Configurez l’authentification entre cert-manager et le coffre à l’aide d’une méthode de choix, comme SAT.
Configurer l'émetteur de certificat du coffre du gestionnaire de certificats.

Activer la gestion automatique des certificats TLS pour un port

Voici un exemple de ressource BrokerListener qui active TLS sur le port 8884 avec la gestion automatique des certificats.

Dans le Portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Sélectionnez ou créez un écouteur. Vous ne pouvez créer qu’un seul écouteur par type de service. Si vous avez déjà un écouteur du même type de service, vous pouvez ajouter d’autres ports à l’écouteur existant.

Vous pouvez ajouter des paramètres TLS à l’écouteur en sélectionnant le protocole TLS sur un port existant ou en ajoutant un nouveau port.

Entrez les paramètres suivants :

Setting	Description
Nom	Nom de la ressource BrokerListener. Saisissez `aio-broker-loadbalancer-tls`.
Port	Numéro de port sur lequel BrokerListener écoute les connexions MQTT. Entrez 8884.
Authentification	Les informations de référence sur les ressources d’authentification.
Autorisation	Les informations de référence sur les ressources d’autorisation.
TLS	Cliquez sur le bouton Ajouter.
Nom de l'émetteur	Nom de l’émetteur du gestionnaire de certificats. Obligatoire.
Type d’émetteur	Type de l’émetteur du gestionnaire de certificats. Obligatoire.
Groupe d’émetteurs	Groupe de l’émetteur du gestionnaire de certificats. Obligatoire.
Algorithme de clé privée	Algorithme de la clé privée.
Stratégie de rotation de clé privée	Stratégie de rotation de la clé privée.
Noms DNS	Autres noms de l’objet DNS pour le certificat.
Adresses IP	Adresses IP des autres noms de l’objet pour le certificat.
Nom du secret	Secret Kubernetes contenant un certificat client X.509.
Durée	Durée de vie totale du certificat de serveur TLS (par défaut : 90 jours).
Renouveler avant	Quand commencer le renouvellement du certificat.

Sélectionnez Appliquer pour enregistrer les paramètres TLS.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = 'aio-broker-loadbalancer-tls'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8884
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'my-issuer'
              kind: 'Issuer'
            }
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Modifiez le paramètre tls dans une ressource BrokerListener de façon à spécifier un port TLS et un Émetteur pour les front-ends.

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer
  ports:
  - port: 8884 # Avoid conflicts with default port 18883
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: my-issuer
          kind: Issuer

Une fois la ressource BrokerListener configurée, l’agent MQTT crée automatiquement un service avec le port spécifié et TLS activé.

Facultatif : Configurer les paramètres de certificat de serveur

Les seuls paramètres obligatoires sont le Nom de l’émetteur et le Type de l’émetteur. Toutes les autres propriétés des certificats de serveur TLS générés sont choisies automatiquement. Toutefois, l’Agent MQTT permet la personnalisation de certaines propriétés en suivant la même syntaxe que les certificats de cert-manager. Par exemple, vous pouvez spécifier l’algorithme de clé privée et la stratégie de rotation. Ces paramètres se trouvent sous tls.certManagerCertificateSpec ou dans le volet Configuration TLS sur le Portail Azure.

Pour obtenir la liste complète de ces paramètres, consultez les Informations de référence sur l’API CertManagerCertificateSpec de l’écouteur de répartiteur.

Vérifier le déploiement

Utilisez kubectl pour vérifier que le service associé à la ressource BrokerListener est en cours d’exécution. Dans l’exemple ci-dessus, le nom du service est aio-broker-loadbalancer-tls et l’espace de noms est azure-iot-operations. La commande suivante vérifie l’état du service :

$ kubectl get service my-new-tls-listener -n azure-iot-operations
NAME                           TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
aio-broker-loadbalancer-tls    LoadBalancer   10.X.X.X        172.X.X.X     8884:32457/TCP   33s

Se connecter au répartiteur avec TLS

Une fois le certificat de serveur configuré, TLS est activé. Pour tester avec mosquitto :

mosquitto_pub -h $HOST -p 8884 -V mqttv5 -i "test" -t "test" -m "test" --cafile ca.crt

L’argument --cafile active TLS sur le client mosquitto et spécifie que le client doit approuver tous les certificats de serveur émis par le fichier donné. Vous devez spécifier un fichier qui contient l’émetteur du certificat de serveur TLS configuré.

Remplacez $HOST par l’hôte approprié :

Si vous vous connectez à partir du même cluster, remplacez par le nom du service donné (my-new-tls-listener par exemple) ou le service CLUSTER-IP.
Si vous vous connectez à partir de l’extérieur du cluster, le service EXTERNAL-IP.

N’oubliez pas de spécifier les méthodes d’authentification si nécessaire.

Autorité de certification racine et émetteur par défaut

Pour vous aider à commencer, Opérations Azure IoT est déployé avec un certificat d’autorité de certification « démarrage rapide » par défaut et un émetteur pour les certificats de serveur TLS. Vous pouvez utiliser cet émetteur pour le développement et le test. Pour plus d’informations, voir AC racine par défaut et émetteur des certificats de serveur TLS.

Pour la production, vous devez configurer un émetteur d’autorité de certification avec un certificat d’une autorité de certification approuvée, comme décrit dans les sections précédentes.

Configurer TLS avec la gestion manuelle des certificats

Pour configurer manuellement l’Agent MQTT pour utiliser un certificat TLS spécifique, spécifiez-le dans une ressource BrokerListener avec une référence à un secret Kubernetes et déployez-le avec kubectl. Cet article montre un exemple de configuration du protocole TLS avec des certificats auto-signés à des fins de test.

Créer une autorité de certification avec Step CLI

Step est un gestionnaire de certificats qui peut rapidement vous rendre opérationnel lors de la création et de la gestion de votre propre autorité de certification privée.

Installez Step CLI et créez un certificat et une clé d’autorité de certification racine.
```
step certificate create --profile root-ca "Example Root CA" root_ca.crt root_ca.key
```

Créez un certificat d’autorité de certification intermédiaire et une clé signés par l’autorité de certification racine.

step certificate create --profile intermediate-ca "Example Intermediate CA" intermediate_ca.crt intermediate_ca.key \
--ca root_ca.crt --ca-key root_ca.key

Créer un certificat de serveur

Utilisez Step CLI pour créer un certificat de serveur à partir de l’autorité de certification intermédiaire signée.

step certificate create mqtts-endpoint mqtts-endpoint.crt mqtts-endpoint.key \
--profile leaf \
--not-after 8760h \
--san mqtts-endpoint \
--san localhost \
--ca intermediate_ca.crt --ca-key intermediate_ca.key \
--no-password --insecure

Ici, mqtts-endpoint et localhost sont les Subject Alternative Names (SAN) pour le front-end de l’agent MQTT dans Kubernetes et les clients locaux, respectivement. Pour vous connecter via Internet, ajoutez un --san avec une adresse IP externe. Les indicateurs --no-password --insecure sont utilisés pour le test pour ignorer les invites de mot de passe et désactiver la protection par mot de passe pour la clé privée, car elles sont stockées dans un secret Kubernetes. Pour la production, utilisez un mot de passe et stockez la clé privée dans un emplacement sécurisé comme Azure Key Vault.

Exigences relatives à l’algorithme de clé de certificat

Les clés EC et RSA sont prises en charge, mais tous les certificats de la chaîne doivent utiliser le même algorithme de clé. Si vous importez vos propres certificats d’autorité de certification, vérifiez que le certificat de serveur utilise le même algorithme de clé que les autorités de certification.

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Créez une chaîne de certificats de serveur complète, où l’ordre des certificats importe : le certificat de serveur est le premier du fichier, le certificat intermédiaire est le second.
```
cat  mqtts-endpoint.crt intermediate_ca.crt  > server_chain.crt
```

Créez un secret Kubernetes avec la chaîne de certificats de serveur et la clé de serveur en utilisant kubectl.

kubectl create secret tls server-cert-secret -n azure-iot-operations \
--cert server_chain.crt \
--key mqtts-endpoint.key

Activer la gestion manuelle des certificats TLS pour un port

Voici un exemple de ressource BrokerListener qui active TLS sur le port 8884 avec la gestion manuelle des certificats.

Dans le portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Sélectionnez ou créez un écouteur. Vous ne pouvez créer qu’un seul écouteur par type de service. Si vous avez déjà un écouteur du même type de service, vous pouvez ajouter d’autres ports à l’écouteur existant. Pour suivre l’exemple, spécifiez le nom du service d’écouteur en tant que mqtts-endpoint.

Vous pouvez ajouter des paramètres TLS à l’écouteur en sélectionnant le protocole TLS sur un port existant ou en ajoutant un nouveau port.

Entrez les paramètres suivants :

Setting	Description
Port	Numéro de port sur lequel BrokerListener écoute les connexions MQTT. Obligatoire.
Authentification	Les informations de référence sur les ressources d’authentification.
Autorisation	Les informations de référence sur les ressources d’autorisation.
TLS	Cliquez sur le bouton Ajouter.
Nom du secret	Secret Kubernetes contenant un certificat client X.509.

Sélectionnez Appliquer pour enregistrer les paramètres TLS.

Modifiez le paramètre tls dans une ressource BrokerListener pour spécifier une configuration TLS manuelle référençant le secret Kubernetes. Notez le nom du secret utilisé pour le certificat de serveur TLS (server-cert-secret dans l’exemple précédent).

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerServiceName string = 'mqtts-endpoint'
param listenerName string = '<LISTENER_NAME>' // Match the SAN in the server certificate

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceName: listenerServiceName
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8885 // Avoid port conflict with default listener at 18883
        tls: {
          mode: 'Manual'
          manual: {
            secretRef: 'server-cert-secret'
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: loadbalancer-tls
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer # Optional, defaults to clusterIP
  serviceName: mqtts-endpoint # Match the SAN in the server certificate
  ports:
  - port: 8885 # Avoid port conflict with default listener at 18883
    tls:
      mode: Manual
      manual:
        secretRef: server-cert-secret

Une fois la ressource BrokerListener créée, l’opérateur crée automatiquement un service Kubernetes et déploie l’écouteur. Vous pouvez vérifier l’état du service en exécutant kubectl get svc.

Se connecter au répartiteur avec TLS

Pour tester la connexion TLS avec le client mosquitto, publiez un message et passez le certificat d’autorité de certification racine dans le paramètre --cafile.

mosquitto_pub -d -h localhost -p 8885 -i "my-client" -t "test-topic" -m "Hello" --cafile root_ca.crt

N’oubliez pas de spécifier le nom d’utilisateur, le mot de passe, etc. si l’authentification de l’agent MQTT est activée.

Client my-client sending CONNECT
Client my-client received CONNACK (0)
Client my-client sending PUBLISH (d0, q0, r0, m1, 'test-topic', ... (5 bytes))
Client my-client sending DISCONNECT

Conseil

Pour utiliser localhost, le port doit être disponible sur l’ordinateur hôte. Par exemple : kubectl port-forward svc/mqtts-endpoint 8885:8885 -n azure-iot-operations. Avec certaines distributions Kubernetes comme K3d, vous pouvez ajouter un port transféré avec k3d cluster edit $CLUSTER_NAME --port-add 8885:8885@loadbalancer.

Remarque

Pour vous connecter au répartiteur, vous devez distribuer la racine de confiance, également connu sous le nom de pack d’approbation, à tous les clients. Dans ce cas, la racine de confiance est l’autorité de certification racine auto-signée créée avec l’interface CLI Step. La distribution de la racine de confiance est requise pour que le client puisse vérifier la chaîne de certificats de serveur. Si vos clients MQTT sont des charges de travail sur le cluster Kubernetes, vous devez également créer un ConfigMap avec l’autorité de certification racine et le monter dans votre pod.

Utiliser une adresse IP externe pour le certificat de serveur

Pour vous connecter à TLS via Internet, le certificat de serveur de l’Agent MQTT doit avoir son nom d’hôte externe ou son adresse IP en tant que SAN. En production, il s’agit généralement d’un nom DNS ou d’une adresse IP connue. Toutefois, pendant le développement/test, vous ne savez peut-être pas quel nom d’hôte ou adresse IP externe est affecté avant le déploiement. Pour résoudre ce problème, déployez d’abord l’écouteur sans le certificat de serveur, puis créez le certificat de serveur et le secret avec l’adresse IP externe, puis importez le secret dans l’écouteur.

Si vous essayez de déployer l’exemple d’écouteur TLS manual-tls-listener mais que le secret Kubernetes référencé server-cert-secret n’existe pas, le service associé est créé, mais les pods ne démarrent pas. Le service est créé, car l’opérateur doit réserver l’adresse IP externe pour l’écouteur.

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

Toutefois, ce comportement est attendu lors de l’importation du certificat de serveur. Les journaux du gestionnaire d’intégrité mentionnent que l’agent MQTT attend le certificat de serveur.

kubectl logs -l app=health-manager -n azure-iot-operations

...
<6>2023-11-06T21:36:13.634Z [INFO] [1] - Server certificate server-cert-secret not found. Awaiting creation of secret.

Remarque

En règle générale, dans un système distribué, les journaux des pods ne sont pas déterministes et doivent être utilisés avec précaution. La bonne façon d’obtenir des informations comme celle-ci consiste à utiliser des événements Kubernetes et l’état des ressources personnalisées, qui se trouve dans le backlog. Considérez l’étape précédente comme solution de contournement temporaire.

Même si les pods frontaux ne sont pas en cours, l’adresse IP externe est déjà disponible.

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

À partir de là, suivez les mêmes étapes que précédemment pour créer un certificat de serveur avec cette adresse IP externe dans --san et créer le secret Kubernetes de la même façon. Une fois le secret créé, il est automatiquement importé dans l’écouteur.

Partager via

Sécuriser la communication de l’Agent MQTT à l’aide de BrokerListener

BrokerListener par défaut

Éviter de modifier l’écouteur de répartiteur par défaut

Créer des écouteurs de broker

Exemple : Créer un écouteur avec deux ports

Type de service

Un seul écouteur par type de service

Nom du service

Ports

Utilisation du même port sur plusieurs écouteurs

Prise en charge des WebSockets

Configurer TLS avec la gestion automatique des certificats

Vérifier l’installation du gestionnaire de certificats

Créer un émetteur pour le certificat de serveur TLS

Configurer le certificat racine en tant que secret Kubernetes

Distribuer le certificat racine

Créer un émetteur basé sur un certificat d’autorité de certification

Activer la gestion automatique des certificats TLS pour un port

Facultatif : Configurer les paramètres de certificat de serveur

Vérifier le déploiement

Se connecter au répartiteur avec TLS

Autorité de certification racine et émetteur par défaut

Configurer TLS avec la gestion manuelle des certificats

Créer une autorité de certification avec Step CLI

Créer un certificat de serveur

Exigences relatives à l’algorithme de clé de certificat

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Activer la gestion manuelle des certificats TLS pour un port

Se connecter au répartiteur avec TLS

Utiliser une adresse IP externe pour le certificat de serveur

Commentaires

Ressources supplémentaires

Partager via

Sécuriser la communication de l’Agent MQTT à l’aide de BrokerListener

BrokerListener par défaut

Éviter de modifier l’écouteur de répartiteur par défaut

Créer des écouteurs de broker

Exemple : Créer un écouteur avec deux ports

Type de service

Un seul écouteur par type de service

Nom du service

Ports

Utilisation du même port sur plusieurs écouteurs

Prise en charge des WebSockets

Configurer TLS avec la gestion automatique des certificats

Vérifier l’installation du gestionnaire de certificats

Créer un émetteur pour le certificat de serveur TLS

Configurer le certificat racine en tant que secret Kubernetes

Distribuer le certificat racine

Créer un émetteur basé sur un certificat d’autorité de certification

Activer la gestion automatique des certificats TLS pour un port

Facultatif : Configurer les paramètres de certificat de serveur

Vérifier le déploiement

Se connecter au répartiteur avec TLS

Autorité de certification racine et émetteur par défaut

Configurer TLS avec la gestion manuelle des certificats

Créer une autorité de certification avec Step CLI

Créer un certificat de serveur

Exigences relatives à l’algorithme de clé de certificat

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Activer la gestion manuelle des certificats TLS pour un port

Se connecter au répartiteur avec TLS

Utiliser une adresse IP externe pour le certificat de serveur

Contenu connexe

Commentaires

Ressources supplémentaires