Configuración de la autenticación del corredor MQTT

Artículo
12/09/2024

Importante

En esta página se incluyen instrucciones para administrar componentes de Operaciones de IoT de Azure mediante manifiestos de implementación de Kubernetes, que se encuentra en versión preliminar. Esta característica se proporciona con varias limitacionesy no se debe usar para cargas de trabajo de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

El agente MQTT admite varios métodos de autenticación para los clientes y puede configurar cada puerto de escucha para tener sus propias opciones de autenticación con un recurso de BrokerAuthentication. Para obtener una lista de la configuración disponible, consulte la referencia de API Autenticación de Broker.

Vinculación de BrokerListener y BrokerAuthentication

Las reglas siguientes se aplican a la relación entre los recursos BrokerListener y BrokerAuthentication:

Cada instancia de BrokerListener puede tener varios puertos. Cada puerto se puede vincular a un recurso BrokerAuthentication.
Cada recurso BrokerAuthentication puede admitir varios métodos de autenticación a la vez.
Los puertos que no vinculan un recurso de BrokerAuthentication tienen deshabilitada la autenticación.

Para vincular un puerto BrokerListener a un recurso de BrokerAuthentication, especifique el campo authenticationRef en la configuración de ports del recurso BrokerListener. Para más información, consulte Recurso BrokerListener.

Recurso BrokerAuthentication predeterminado

Operaciones de IoT de Azure implementa un recurso predeterminado BrokerAuthentication denominado default vinculado con el cliente de escucha predeterminado en el espacio de nombres azure-iot-operations. Solo usa Tokens de cuenta de Servicio de Kubernetes (SAT) para la autenticación.

Importante

El método de autenticación de token de cuenta de servicio (SAT) en el recurso BrokerAuthentication predeterminado es necesario para que los componentes de Operaciones de IoT de Azure funcionen correctamente. Evite actualizar o eliminar el recurso predeterminado BrokerAuthentication.

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione la pestaña Autenticación.
En la lista de directivas de autenticación, seleccione el nombre de directiva predeterminado .

Para agregar nuevos métodos de autenticación, seleccione Agregar método.

Para editar el punto de conexión predeterminado, cree un archivo .bicep de Bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por los suyos propios.

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 defaultBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
          ]
        }
      }
    ]
  }
}

Implementación de archivo Bicep mediante la CLI de Azure.

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

Para inspeccionar el recurso de autenticación de agente predeterminado, ejecute:

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

La salida muestra el recurso BrokerAuthentication predeterminado (para mayor brevedad, los metadatos se han quitado):

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata:
  name: default
  namespace: azure-iot-operations
spec:
  authenticationMethods:
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
          - aio-internal

Si necesita realizar cambios, modifique el campo authenticationMethods de este recurso mientras conserva el método de autenticación SAT con la audiencia de aio-internal. A continuación, impleméntelo mediante kubectl apply.

Flujo de autenticación

El orden de los métodos de autenticación especificados determina cómo el agente MQTT autentica a los clientes. El agente MQTT intenta autenticar las credenciales del cliente mediante el primer método especificado y recorre en iteración los métodos especificados hasta que encuentre una coincidencia o llegue al final.

Para cada método, corredor MQTT comprueba primero si las credenciales del cliente son pertinentes para ese método. Por ejemplo, la autenticación SAT requiere un nombre de usuario que empiece por K8S-SAT y la autenticación X.509 requiere un certificado de cliente. Si las credenciales del cliente son pertinentes, corredor MQTT comprueba si son válidas. Para más información, consulte Configuración del método de autenticación.

Para la autenticación personalizada, el error para comunicarse con el servidor de autenticación personalizado se trata en corredor MQTT como que las credenciales no son pertinentes. Este comportamiento permite que el agente MQTT vuelva a otros métodos si el servidor de autenticación personalizado no es accesible.

El flujo de autenticación finaliza cuando:

Se cumple una de estas condiciones:
- Las credenciales del cliente son pertinentes y válidas para uno de los métodos.
- Las credenciales del cliente no son pertinentes para ninguno de los métodos.
- Las credenciales del cliente son pertinentes, pero no son válidas para ninguno de los métodos.
El corredor MQTT concede o deniega el acceso al cliente en función del resultado del flujo de autenticación.

Por ejemplo:

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata: 
  name: default
  namespace: azure-iot-operations
spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # ...
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        # ...

En el ejemplo anterior se especifican personalizada y SAT. Cuando un cliente se conecta, el agente MQTT intenta autenticar al cliente mediante los métodos especificados en el orden personalizado y, a continuación, SAT.

El corredor MQTT comprueba si las credenciales del cliente son válidas para la autenticación personalizada. Dado que la autenticación personalizada se basa en un servidor externo para determinar la validez de las credenciales, el agente considera todas las credenciales pertinentes para la autenticación personalizada y las reenvía al servidor de autenticación personalizada.
Si el servidor de autenticación personalizada responde con Pass o Fail, finaliza el flujo de autenticación. Pero si el servidor de autenticación personalizada no está disponible, el corredor MQTT recurre al resto de métodos especificados, donde SAT es el siguiente.
El corredor MQTT intenta autenticar las credenciales como credenciales SAT.

Si el servidor de autenticación personalizada no está disponible y todos los métodos posteriores determinaron que las credenciales proporcionadas no son pertinentes, el agente deniega la conexión del cliente.

Configuración del método de autenticación

Puede agregar métodos de autenticación como X.509, SAT o personalizados a las directivas de autenticación.

Para agregar un método de autenticación a una directiva:

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione la pestaña Autenticación.
Elija una directiva de autenticación existente o cree una nueva.
Para agregar un nuevo método, seleccione Agregar método.
Elija el tipo de método en la lista desplegable y seleccione Agregar detalles para configurar el método.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_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 myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'Custom'
        customSettings: {
          endpoint: 'https://auth-server-template'
          caCertConfigMap: 'custom-auth-ca'
          auth: {
            x509: {
              secretRef: 'custom-auth-client-cert'
            }
          }
          headers: {
            header_key: 'header_value'
          }
        }
      }
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
      {
        method: 'X509'
        x509Settings: {
          trustedClientCaCert: 'client-ca'
          authorizationAttributes: {
            root: {
              attributes: {
                organization: 'contoso'
              }
              subject: 'CN = Contoso Root CA Cert, OU = Engineering, C = US'
            }
            intermediate: {
              attributes: {
                city: 'seattle'
                foo: 'bar'
              }
              subject: 'CN = Contoso Intermediate CA'
            }
            smartfan: {
              attributes: {
                building: '17'
              }
              subject: 'CN = smart-fan'
            }
          }
        }
      }
    ]
  }
}

Implementación de archivo Bicep mediante la CLI de Azure.

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

Modifique el recurso BrokerAuthentication para una directiva de autenticación agregando nuevos métodos a la authenticationMethods sección. En el ejemplo siguiente se muestran varios métodos de autenticación para un recurso BrokerAuthentication:

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata:
  name: my-policy
  namespace: azure-iot-operations
spec:
  authenticationMethods:
  - method: Custom
    customSettings:
      endpoint: https://auth-server-template
      caCertConfigMap: custom-auth-ca
      auth:
        x509:
          secretRef: custom-auth-client-cert
      headers:
        header_key: header_value
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
        - aio-internal
        - my-audience
    - method: X509
      x509Settings:
        trustedClientCaCert: client-ca
        authorizationAttributes:
          root:
            attributes:
              organization: contoso
            subject: CN = Contoso Root CA Cert, OU = Engineering, C = US
          intermediate:
            attributes:
              city: seattle
              foo: bar
            subject: CN = Contoso Intermediate CA
          smart-fan:
            attributes:
              building: "17"
            subject: CN = smart-fan

Para cambiar la configuración, modifique laauthenticationMethods configuración en este recurso de BrokerAuthentication, a continuación, impleméntela mediante kubectl apply.

Para obtener más información sobre cada una de las opciones de autenticación, consulte las siguientes secciones para cada método.

Para más información sobre cómo habilitar la configuración segura mediante la configuración de Azure Key Vault y la habilitación de identidades de carga de trabajo, consulte Habilitar la configuración segura en la implementación de Operaciones de IoT de Azure.

X.509

Sugerencia

Para obtener un ejemplo completo de cómo configurar la autenticación X.509, consulte Tutorial: TLS, autenticación de cliente X.509, autenticación de cliente X.509 y autorización de control de acceso basado en atributos (ABAC).

Con la autenticación X.509, el agente MQTT usa un certificado de entidad de certificación de confianza para validar los certificados de cliente. Esta entidad de certificación de confianza puede ser una entidad de certificación raíz o intermedia. El agente comprueba la cadena de certificados de cliente con el certificado de entidad de certificación de confianza. Si la cadena es válida, el cliente se autentica.

Para usar la autenticación X.509 con un certificado de entidad de certificación de confianza, se deben cumplir los siguientes requisitos:

TLS: Dado que X.509 se basa en certificados de cliente TLS, TLS debe estar habilitado para los puertos que usan la autenticación X.509.
Algoritmos de clave: Se admiten claves EC y RSA, pero todos los certificados de la cadena deben usar el mismo algoritmo de clave.
Formato: El certificado de entidad de certificación debe estar en formato PEM.

Sugerencia

El formato PEM es un formato común para certificados y claves. Los archivos PEM son archivos ASCII codificados en base64 con encabezados como -----BEGIN CERTIFICATE----- y -----BEGIN EC PRIVATE KEY-----.

Si tiene un certificado en otro formato, puede convertirlo a PEM mediante OpenSSL. Para obtener más información, vea Cómo convertir un certificado en el formato adecuado.

Obtención de un certificado de entidad de certificación de confianza

En una configuración de producción, el certificado de entidad de certificación lo proporciona la infraestructura de clave pública (PKI) de una organización o una entidad de certificación pública.

Para las pruebas, cree un certificado de entidad de certificación autofirmado con OpenSSL. Por ejemplo, ejecute el siguiente comando para generar un certificado de entidad de certificación autofirmado con una clave RSA, un nombre distintivo CN=Contoso Root CA Cert, y una validez de 365 días:

openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca.pem -days 365 -nodes -subj "/CN=Contoso Root CA Cert"

El mismo comando con CLI de paso, que es una herramienta cómoda para administrar certificados, es:

step certificate create "Contoso Root CA Cert" ca.pem ca-key.pem --profile root-ca --kty RSA --size 4096 --no-password --insecure
 --not-after 8760h

Estos comandos crean un certificado de entidad de certificación ca.pem y una clave privada ca-key.pem en formato PEM. El certificado de entidad de certificación ca.pem se puede importar al agente MQTT para la autenticación X.509.

Importar un certificado de CA de confianza

Para empezar a trabajar con la autenticación X.509, importe el certificado de entidad de certificación de confianza en ConfigMap en el espacio de nombres azure-iot-operations. Para importar un certificado de entidad de certificación de confianza ca.pem en un objeto ConfigMap denominado client-ca, ejecute:

kubectl create configmap client-ca --from-file=ca.pem -n azure-iot-operations

En este ejemplo, el certificado de entidad de certificación se importa en la clave ca.pem. El agente MQTT confía en todos los certificados de entidad de certificación en ConfigMap, por lo que el nombre de la clave puede ser cualquier cosa.

Para comprobar que el certificado de CA raíz se ha importado correctamente, ejecute kubectl describe configmap. El resultado muestra la misma codificación en base64 del archivo de certificado PEM.

kubectl describe configmap client-ca -n azure-iot-operations

Name:         client-ca
Namespace:    azure-iot-operations

Data
====
ca.pem:
----
-----BEGIN CERTIFICATE-----
MIIFDjCCAvagAwIBAgIRAKQWo1+S13GTwqZSUYLPemswDQYJKoZIhvcNAQELBQAw
...
-----END CERTIFICATE-----


BinaryData
====

Configuración del método de autenticación X.509

Una vez importado el certificado de entidad de certificación de confianza, habilite la autenticación de cliente X.509 agregándola como método de autenticación en un recurso de BrokerAuthentication. Asegúrese de que este recurso esté vinculado a un puerto de escucha habilitado para TLS.

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione la pestaña Autenticación.
Elija una directiva de autenticación existente o cree una nueva.
Para agregar un nuevo método, seleccione Agregar método.
Elija el tipo de método X.509 en la lista desplegable y seleccione Agregar detalles para configurar el método.
En el panel detalles de autenticación X.509, especifique el nombre ConfigMap del certificado de entidad de certificación de confianza con formato JSON.
```
{
    "trustedClientCaCert": "<TRUSTED_CA_CONFIGMAP>"
}
```
Reemplace <TRUSTED_CA_CONFIGMAP> por el nombre de ConfigMap que contiene el certificado de entidad de certificación de confianza. Por ejemplo, "trustedClientCaCert": "client-ca".
Opcionalmente, agregue atributos de autorización para los clientes que usan certificados X.509. Para más información, consulte atributos de certificado para la autorización.
Seleccione Aplicar para guardar los cambios.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'
param trustedCaConfigMap string = '<TRUSTED_CA_CONFIGMAP>'

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 myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'X509'
        x509Settings: {
          trustedClientCaCert: trustedCaConfigMap
          // authorizationAttributes: {
            //// Optional authorization attributes
            //// See the next section for more information
          // }
        }
      }
    ]
  }
}

Reemplace <TRUSTED_CA_CONFIGMAP> por el nombre de ConfigMap que contiene el certificado de entidad de certificación de confianza. Por ejemplo, client-ca.

Implementación de archivo Bicep mediante la CLI de Azure.

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

spec:
  authenticationMethods:
    - method: X509
      x509Settings:
        trustedClientCaCert: <TRUSTED_CA_CONFIGMAP>
        # authorizationAttributes:
          ## Optional authorization attributes
          ## See the next section for more information

Reemplace <TRUSTED_CA_CONFIGMAP> por el nombre de ConfigMap que contiene el certificado de entidad de certificación de confianza. Por ejemplo, client-ca.

Opcional: Atributos de certificado para la autorización

Los atributos X.509 se pueden especificar en el recurso BrokerAuthentication para autorizar a los clientes en función de sus propiedades de certificado. Los atributos se definen en el campo authorizationAttributes.

Por ejemplo:

En Azure Portal, al configurar el método de autenticación X.509, agregue los atributos de autorización en el panel detalles de autenticación X.509 en formato JSON.

{
  "trustedClientCaCert": "<TRUSTED_CA_CONFIGMAP>",
  "authorizationAttributes": {
    "root": {
      "subject": "CN = Contoso Root CA Cert, OU = Engineering, C = US",
      "attributes": {
        "organization": "contoso"
      }
    },
    "intermediate": {
      "subject": "CN = Contoso Intermediate CA",
      "attributes": {
        "city": "seattle",
        "foo": "bar"
      }
    },
    "smartfan": {
      "subject": "CN = smart-fan",
      "attributes": {
        "building": "17"
      }
    }
  }
}

x509Settings: {
  trustedClientCaCert: '<TRUSTED_CA_CONFIGMAP>'
  authorizationAttributes: {
    root: {
      subject: 'CN = Contoso Root CA Cert, OU = Engineering, C = US'
      attributes: {
        organization: 'contoso'
      }
    }
    intermediate: {
      subject: 'CN = Contoso Intermediate CA'
      attributes: {
        city: 'seattle'
        foo: 'bar'
      }
    }
    smartfan: {
      subject: 'CN = smart-fan'
      attributes: {
        building: '17'
      }
    }
  }
}

x509Settings:
  trustedClientCaCert: <TRUSTED_CA_CONFIGMAP>
  authorizationAttributes:
    root:
      subject = "CN = Contoso Root CA Cert, OU = Engineering, C = US"
      attributes:
        organization = contoso
    intermediate:
      subject = "CN = Contoso Intermediate CA"
      attributes:
        city = seattle
        foo = bar
    smart-fan:
      subject = "CN = smart-fan"
      attributes:
        building = 17

En este ejemplo, cada cliente que tiene un certificado emitido por la entidad de certificación raíz con nombre distintivo CN = Contoso Root CA Cert, OU = Engineering, C = US o la entidad de certificación intermedia con nombre distintivo CN = Contoso Intermediate CA recibe los atributos enumerados. Además, el certificado de cliente de ventilador inteligente recibe atributos específicos de él.

La coincidencia de atributos siempre comienza desde el certificado de cliente hoja y, a continuación, pasa por la cadena. La asignación de atributos se detiene después de la primera coincidencia. En el ejemplo anterior, incluso si smart-fan tiene el certificado intermedio CN = Contoso Intermediate CA, no obtiene los atributos asociados.

Se pueden aplicar reglas de autorización a los clientes que usan certificados X.509 con estos atributos. Para obtener más información, consulte Autorización de clientes que usan la autenticación X.509.

Habilitación de la autenticación X.509 para un puerto de escucha

Después de importar el certificado de entidad de certificación de confianza y configurar el recurso de BrokerAuthentication, vincule a un puerto de escucha habilitado para TLS. Este paso es importante porque la autenticación X.509 se basa en TLS para la validación de certificados de cliente.

Para obtener un puerto de escucha habilitado para TLS, consulte Habilitación de la administración manual de certificados TLS para un puerto y Habilitación de la administración automática de certificados TLS para un puerto.

Nota:

Habilitar TLS en un puerto de agente de escucha significa que el agente usa un certificado de servidor para el cifrado TLS. Cuando los clientes se conectan a este puerto, deben confiar en el certificado de servidor al tener el certificado de entidad de certificación que lo firmó en su almacén de confianza. Este proceso se conoce como distribución de confianza o agrupación de confianza. Es importante comprender la diferencia entre la validación del servidor y la validación de cliente:

Validación de cliente: El agente MQTT (servidor) comprueba el certificado de cliente con el certificado de entidad de certificación de confianza especificado en el campo trustedClientCaCert para la autenticación de cliente X.509.
Validación del servidor: Los clientes (como mosquitto o MQTTX) comprueban el certificado de servidor del agente MQTT con el certificado de entidad de certificación de confianza en su almacén de confianza. Para los clientes de mosquitto, use el parámetro --cafile para especificar el archivo de certificado de entidad de certificación. Para MQTTX, agregue el certificado de entidad de certificación al almacén de confianza en la configuración.

Después de habilitar la autenticación X.509, asegúrese de que los clientes confíen en el certificado de servidor del agente al tener el certificado de entidad de certificación del lado servidor en su almacén de confianza. No confunda la confianza en el certificado de entidad de certificación del lado servidor con el certificado de entidad de certificación del lado cliente usado para la autenticación de cliente que se especifica en el campo trustedClientCaCert.

Para obtener un ejemplo completo, consulte Tutorial: Autenticación de cliente TLS, X.509 y autorización de control de acceso basado en atributos (ABAC).

Conexión del cliente mosquitto a corredor MQTT con un certificado de cliente X.509

Un cliente como mosquitto necesita dos archivos para poder conectarse al corredor MQTT con la autenticación de cliente TLS y X.509.

El parámetro --cert especifica el archivo PEM del certificado de cliente. Este archivo también debe incluir cualquier certificado intermedio para ayudar al agente MQTT a crear la cadena de certificados completa.
El parámetro --key especifica el archivo PEM de la clave privada de cliente.

En los casos en los que el agente MQTT usa un certificado de entidad de certificación autofirmado para emitir su certificado de servidor TLS, se necesita el parámetro --cafile. Este archivo contiene el certificado de entidad de certificación (también conocido como agrupación de confianza) que usa el cliente mosquitto para validar el certificado de servidor del agente al conectarse a través de TLS. Si el emisor del certificado de servidor del agente MQTT forma parte del almacén raíz del sistema (como CA públicas conocidas), se puede omitir el parámetro --cafile.

Por ejemplo:

mosquitto_pub -q 1 -t hello -d -V mqttv5 -m world -i thermostat \
-h "<BROKER_HOST>" \
--cert thermostat_cert.pem \
--key thermostat_key.pem \
--cafile ca.pem

Descripción del flujo de autenticación de cliente X.509 del corredor MQTT

Diagrama del flujo de autenticación de cliente X.509.

Estos son los pasos para la autenticación de cliente:

Cuando se activa la autenticación de cliente X.509, los clientes que se conectan deben presentar su certificado de cliente y los certificados intermedios para permitir que el corredor MQTT cree una cadena de certificados con la raíz en uno de sus certificados de confianza configurados.
El equilibrador de carga dirige la comunicación a uno de los agentes de front-end.
Una vez que el agente de front-end recibe el certificado de cliente, intenta crear una cadena de certificados que tiene como raíz uno de los certificados configurados. Si el agente de front-end ha creado correctamente una cadena y se comprueba la cadena presentada, finaliza el protocolo de enlace TLS. El cliente de conexión puede enviar paquetes MQTT al front-end mediante el canal TLS.
El canal TLS está abierto, pero la autenticación o autorización de cliente aún no ha finalizado.
Después, el cliente envía un paquete CONNECT al corredor MQTT.
El paquete CONNECT se enruta de nuevo a un front-end.
El front-end recopila todas las credenciales que el cliente presentó hasta ahora, como los datos de autenticación del paquete CONNECT y la cadena de certificados de cliente presentadas durante el protocolo de enlace TLS.
El front-end envía estas credenciales al servicio de autenticación. El servicio de autenticación comprueba de nuevo la cadena de certificados y recopila los nombres de firmante de todos los certificados de la cadena.
El servicio de autenticación usa sus reglas de autorización configuradas para determinar qué atributos tienen los clientes que se conectan. Estos atributos determinan qué operaciones puede ejecutar el cliente, incluido el propio paquete CONNECT.
El servicio de autenticación devuelve la decisión al agente de front-end.
El agente de front-end conoce los atributos de cliente y si se le permite conectarse. Si es así, la conexión MQTT se completa y el cliente puede seguir enviando y recibiendo paquetes MQTT según lo determinado por sus reglas de autorización.

Tokens de cuenta de servicio de Kubernetes

Los tokens de cuenta de servicio de Kubernetes (SAT) son tokens JSON Web Token asociados a cuentas de servicio de Kubernetes. Los clientes presentan SAT al corredor MQTT para autenticarse a sí mismos.

El corredor MQTT usa tokens de cuenta de servicio enlazados que se detallan en la publicación ¿Qué necesitan los usuarios de GKE para conocer los nuevos tokens de cuenta de servicio de Kubernetes?. Estas son las características destacadas de la publicación:

Lanzados en Kubernetes 1.13 y convertidos en el formato predeterminado en la versión 1.21, los tokens enlazados abordan toda la funcionalidad limitada de los tokens heredados, y mucho más:

Los tokens en sí son más difíciles de robar y utilizar indebidamente; están vinculados al tiempo, al público y al objeto.
Adoptan un formato estandarizado: OpenID Connect (OIDC), con detección completa de OIDC, lo que facilita que los proveedores de servicios los acepten.
Se distribuyen a pods de forma más segura mediante un nuevo tipo de volumen proyectado de Kubelet.

El agente comprueba los tokens mediante la API de revisión de tokens de Kubernetes. Habilite la característica TokenRequestProjection de Kubernetes para especificar audiences (valor predeterminado desde la versión 1.21). Si esta característica no está habilitada, no se pueden usar SAT.

Crear una cuenta de servicio

Para crear SAT, primero crear una cuenta de servicio. Con el siguiente comando se crea una cuenta de servicio llamada mqtt-client.

kubectl create serviceaccount mqtt-client -n azure-iot-operations

Opcional: Agregar atributos para la autorización

Los clientes que se autentican a través de SAT pueden tener sus cuentas de servicio anotadas con atributos que se usarán con directivas de autorización. Para distinguir estas anotaciones de otras, comienzan por aio-broker-auth/ prefijo.

Puede anotar una cuenta de servicio mediante kubectl annotate:

kubectl annotate serviceaccount <SERVICE_ACCOUNT_NAME> aio-broker-auth/<ATTRIBUTE>=<VALUE> -n azure-iot-operations

O bien, puede agregar las anotaciones al archivo de manifiesto de la cuenta de servicio:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <SERVICE_ACCOUNT_NAME>
  namespace: azure-iot-operations
  annotations:
    aio-broker-auth/<ATTRIBUTE_1>: <VALUE_1>
    aio-broker-auth/<ATTRIBUTE_2>: <VALUE_2>

Para más información, consulte Autorización de clientes que usan tokens de cuenta de servicio de Kubernetes.

Habilitación de la autenticación de tokens de cuenta de servicio (SAT)

Modifique el valor authenticationMethods de un recurso BrokerAuthentication para especificar ServiceAccountToken como método de autenticación válido. El valor audiences especifica la lista de públicos válidos para tokens. Elija valores únicos que identifiquen el servicio de corredor MQTT. Debe especificar al menos un público y todos los SAT deben coincidir con uno de los públicos especificados.

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione la pestaña Autenticación.
Elija una directiva de autenticación existente o cree una nueva.
Para agregar un nuevo método, seleccione Agregar método.
Elija el tipo de método SAT de Kubernetes en la lista desplegable y, después, seleccione Agregar detalles para configurar el método.

Recorte de pantalla con Azure Portal para establecer el método de autenticación SAT del agente MQTT.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_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 myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
    ]
  }
}

Implementación de archivo Bicep mediante la CLI de Azure.

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

spec:
  authenticationMethods:
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
        - aio-internal
        - my-audience

Aplique los cambios con kubectl apply. Puede que los cambios tarden unos minutos en surtir efecto.

Prueba de la autenticación SAT

La autenticación SAT usa los campos de autenticación mejorados de MQTT v5. Un cliente debe establecer el método de autenticación mejorado en K8S-SAT y los datos de autenticación mejorados en el token.

Por ejemplo, mediante mosquitto (algunos campos omitidos por brevedad):

mosquitto_pub ... -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data <TOKEN>

Aquí, <TOKEN> es el token de la cuenta de servicio. Para obtener un token de prueba, ejecute:

kubectl create token <SERVICE_ACCOUNT> -n azure-iot-operations --audience <AUDIENCE>

Aquí, <SERVICE_ACCOUNT> es el nombre de la cuenta de servicio que creó y <AUDIENCE> es una de las audiencias configuradas en el recurso BrokerAuthentication.

Para obtener un ejemplo sobre cómo configurar un pod de Kubernetes para usar la autenticación SAT, consulte Conectar con el cliente de escucha por defecto dentro del clúster.

En la configuración del pod, el campo serviceAccountName debe coincidir con la cuenta de servicio asociada al token que se usa y el campo serviceAccountToken.audience debe ser uno de los audiences configurados en el recurso BrokerAuthentication.

Actualizar tokens de cuenta de servicio

Los tokens de cuenta de servicio son válidos durante un tiempo limitado y configurados con expirationSeconds. Sin embargo, Kubernetes actualiza automáticamente el token antes de que expire. El token se actualiza en segundo plano y el cliente no necesita hacer nada más que capturarlo de nuevo.

Por ejemplo, si el cliente es un pod que usa el token montado como un volumen, como en el ejemplo de autenticación SAT de prueba, el token más reciente está disponible en la misma ruta de acceso /var/run/secrets/tokens/broker-sat. Al realizar una nueva conexión, el cliente puede capturar el token más reciente y usarlo para autenticarse. El cliente también debe tener un mecanismo para controlar errores no autorizados de MQTT mediante la captura del token más reciente y el reintento de la conexión.

Autenticación personalizada

Amplíe la autenticación de cliente más allá de los métodos de autenticación proporcionados con la autenticación personalizada. Es conectable, ya que el servicio puede ser cualquier cosa siempre que se ajuste a la API.

Cuando un cliente se conecta al agente MQTT con la autenticación personalizada habilitada, el agente envía una solicitud HTTPS a un servidor de autenticación personalizado con las credenciales del cliente. A continuación, el servidor responde con aprobación o denegación, incluidos los atributos de autorización del cliente.

Creación de un servicio de autenticación personalizada

El servidor de autenticación personalizada se implementa por separado del corredor MQTT.

En GitHub, se puede encontrar un ejemplo de servidor de autenticación personalizada e instrucciones. Use este ejemplo como plantilla y punto de partida para implementar su propia lógica de autenticación personalizada.

API

La API entre el corredor MQTT y el servidor de autenticación personalizada sigue la especificación de API de la autenticación personalizada. La especificación openAPI está disponible en GitHub.

Se requiere HTTPS con cifrado TLS

El corredor MQTT envía solicitudes que contienen credenciales de cliente confidenciales al servidor de autenticación personalizado. Para proteger estas credenciales, la comunicación entre el corredor MQTT y el servidor de autenticación personalizada se debe cifrar con TLS.

El servidor de autenticación personalizada debe presentar un certificado de servidor y el corredor MQTT debe tener un certificado de CA raíz de confianza para validarlo. Opcionalmente, el servidor de autenticación personalizada podría exigir que el corredor MQTT presente un certificado de cliente para autenticarse.

Habilitación de la autenticación personalizada para un cliente de escucha

Modifique el valor authenticationMethods de un recurso BrokerAuthentication para especificar Custom como método de autenticación válido. A continuación, especifique los parámetros necesarios para comunicarse con un servidor de autenticación personalizada.

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione la pestaña Autenticación.
Elija una directiva de autenticación existente o cree una nueva.
Para agregar un nuevo método, seleccione Agregar método.
Elija el tipo de método Personalizado en la lista desplegable y seleccione Agregar detalles para configurar el método.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_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 myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'Custom'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
    ]
  }
}

Implementación de archivo Bicep mediante la CLI de Azure.

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

En este ejemplo se muestran todos los parámetros posibles. Los parámetros exactos necesarios dependen de los requisitos personalizados de cada servidor.

spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # Endpoint for custom authentication requests. Required.
        endpoint: https://auth-server-template
        # Optional CA certificate for validating the custom authentication server's certificate.
        caCertConfigMap: custom-auth-ca
        # Authentication between MQTT broker with the custom authentication server.
        # The broker may present X.509 credentials or no credentials to the server.
        auth:
          x509:
            secretRef: custom-auth-client-cert
            namespace: azure-iot-operations
        # Optional additional HTTP headers that the broker will send to the
        # custom authentication server.
        headers:
          header_key: header_value

Deshabilitación de la autenticación

Para realizar pruebas, puede desactivar la autenticación para un puerto de escucha de intermediario. No se recomienda deshabilitar la autenticación para entornos de producción.

En Azure Portal, vaya a su instancia de IoT Hub.
En Componentes, seleccione MQTT Broker.
Seleccione el cliente de escucha del corredor que desea editar en la lista.
En el puerto que desea deshabilitar la autenticación, seleccione Ninguno en la lista desplegable de autenticación.

Los clientes se desconectan después de que expiren las credenciales

El corredor MQTT desconecta los clientes cuando expiran sus credenciales. La desconexión después de la expiración de credenciales se aplica a todos los clientes que se conectan a los front-end del corredor MQTT, incluidos los siguientes:

Los clientes autenticados con SAT se desconectan cuando expira su SAT
Los clientes autenticados con X.509 se desconectan cuando expira su certificado de cliente
Los clientes autenticados con la autenticación personalizada se desconectan en función de la hora de expiración devuelta del servidor de autenticación personalizada.

Al desconectarse, se cierra la conexión de red del cliente. El cliente no recibe un paquete MQTT DISCONNECT, pero el agente registra un mensaje que desconecta el cliente.

Los clientes MQTT v5 autenticados con SAT y la autenticación personalizada se pueden volver a autenticar con una nueva credencial antes de que expire su credencial inicial. Los clientes X.509 no se pueden volver a autenticar y deben volver a establecer la conexión, ya que la autenticación se realiza en la capa TLS.

Los clientes pueden volver a autenticarse enviando un paquete MQTT v5 AUTH por motivo ReAuth.

Los clientes SAT envían un cliente AUTH con los campos method: K8S-SAT, data: <token>. Los clientes de autenticación personalizada establecen el método y el campo de datos según sea necesario para el servidor de autenticación personalizada.

La nueva autenticación correcta actualiza la expiración de las credenciales del cliente con la hora de expiración de su nueva credencial y el agente responde con un paqueteSuccess AUTH. No se pudo realizar la autenticación debido a problemas transitorios, como que el servidor de autenticación personalizado no está disponible, lo que hace que el agente responda con un paquete de AUTH ContinueAuthentication. El cliente puede volver a intentarlo más tarde. Otros errores de autenticación provocan que el agente envíe un paquete DISCONNECT y cierre la conexión de red del cliente.

Compartir vía

Configuración de la autenticación del corredor MQTT

Vinculación de BrokerListener y BrokerAuthentication

Recurso BrokerAuthentication predeterminado

Flujo de autenticación

Configuración del método de autenticación

X.509

Obtención de un certificado de entidad de certificación de confianza

Importar un certificado de CA de confianza

Configuración del método de autenticación X.509

Opcional: Atributos de certificado para la autorización

Habilitación de la autenticación X.509 para un puerto de escucha

Conexión del cliente mosquitto a corredor MQTT con un certificado de cliente X.509

Descripción del flujo de autenticación de cliente X.509 del corredor MQTT

Tokens de cuenta de servicio de Kubernetes

Crear una cuenta de servicio

Opcional: Agregar atributos para la autorización

Habilitación de la autenticación de tokens de cuenta de servicio (SAT)

Prueba de la autenticación SAT

Actualizar tokens de cuenta de servicio

Autenticación personalizada

Creación de un servicio de autenticación personalizada

API

Se requiere HTTPS con cifrado TLS

Habilitación de la autenticación personalizada para un cliente de escucha

Deshabilitación de la autenticación

Los clientes se desconectan después de que expiren las credenciales

Comentarios

Recursos adicionales

Compartir vía

Configuración de la autenticación del corredor MQTT

Vinculación de BrokerListener y BrokerAuthentication

Recurso BrokerAuthentication predeterminado

Flujo de autenticación

Configuración del método de autenticación

X.509

Obtención de un certificado de entidad de certificación de confianza

Importar un certificado de CA de confianza

Configuración del método de autenticación X.509

Opcional: Atributos de certificado para la autorización

Habilitación de la autenticación X.509 para un puerto de escucha

Conexión del cliente mosquitto a corredor MQTT con un certificado de cliente X.509

Descripción del flujo de autenticación de cliente X.509 del corredor MQTT

Tokens de cuenta de servicio de Kubernetes

Crear una cuenta de servicio

Opcional: Agregar atributos para la autorización

Habilitación de la autenticación de tokens de cuenta de servicio (SAT)

Prueba de la autenticación SAT

Actualizar tokens de cuenta de servicio

Autenticación personalizada

Creación de un servicio de autenticación personalizada

API

Se requiere HTTPS con cifrado TLS

Habilitación de la autenticación personalizada para un cliente de escucha

Deshabilitación de la autenticación

Los clientes se desconectan después de que expiren las credenciales

Contenido relacionado

Comentarios

Recursos adicionales