Merge pull request #290848 from jlian/main

Add X.509 tutorial

Author: Jill Grant

articles/iot-operations/connect-to-cloud/tutorial-mqtt-bridge.md

@@ -1,5 +1,5 @@
 ---
-title: Bi-directional MQTT bridge to Azure Event Grid
+title: "Tutorial: Bi-directional MQTT bridge to Azure Event Grid"
 description: Learn how to create a bi-directional MQTT bridge to Azure Event Grid using Azure IoT Operations dataflows.
 author: PatAltimore
 ms.author: patricka

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

@@ -39,7 +39,7 @@ Azure IoT Operations deploys a default *BrokerAuthentication* resource named `de
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authentication** tab.
 1. From authentication policy list, select the **default** policy name.
 
@@ -176,7 +176,7 @@ To add an authentication method to a policy:
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authentication** tab.
 1. Choose an existing authentication policy or create a new one.
 1. Add a new method by selecting **Add method**.
@@ -331,6 +331,9 @@ For more information about enabling secure settings by configuring an Azure Key
 
 ## X.509
 
+> [!TIP]
+> For an end-to-end example of how to configure X.509 authentication, see [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md).
+
 With X.509 authentication, the MQTT broker uses a **trusted CA certificate** to validate client certificates. This trusted CA can be a root or intermediate CA. The broker checks the client certificate chain against the trusted CA certificate. If the chain is valid, the client is authenticated.
 
 To use X.509 authentication with a trusted CA certificate, the following requirements must be met:
@@ -404,7 +407,7 @@ Once the trusted CA certificate is imported, enable X.509 client authentication
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authentication** tab.
 1. Choose an existing authentication policy or create a new one.
 1. Add a new method by selecting **Add method**.
@@ -593,16 +596,27 @@ Authorization rules can be applied to clients using X.509 certificates with thes
 
 ### Enable X.509 authentication for a listener port
 
-After importing the trusted CA certificate and configuring the *BrokerAuthentication* resource, link it to a TLS-enabled listener port. For more details, see [Enable TLS manual certificate management for a port](./howto-configure-brokerlistener.md#enable-tls-manual-certificate-management-for-a-port) and [Enable TLS automatic certificate management for a port](./howto-configure-brokerlistener.md#enable-tls-automatic-certificate-management-for-a-port).
+After importing the trusted CA certificate and configuring the *BrokerAuthentication* resource, link it to a TLS-enabled listener port. This step is important because X.509 authentication relies on TLS for client certificate validation.
 
+To get a TLS-enabled listener port, see [Enable TLS manual certificate management for a port](./howto-configure-brokerlistener.md#enable-tls-manual-certificate-management-for-a-port) and [Enable TLS automatic certificate management for a port](./howto-configure-brokerlistener.md#enable-tls-automatic-certificate-management-for-a-port).
+
+> [!NOTE]
+> Enabling TLS on a broker listener port means the broker uses a server certificate for TLS encryption. When clients connect to this port, they must trust the server certificate by having the CA certificate that signed it in their trust store. This process is known as *trust distribution* or *trust bundling*. It's important to understand the difference between server validation and client validation:
+> 
+> - **Client validation**: The MQTT broker (server) checks the client certificate against the trusted CA certificate specified in the `trustedClientCaCert` field for X.509 client authentication.
+> - **Server validation**: Clients (like mosquitto or MQTTX) check the MQTT broker's server certificate against the trusted CA certificate in their trust store. For mosquitto clients, use the `--cafile` parameter to specify the CA certificate file. For MQTTX, add the CA certificate to the trust store in the settings.
+>
+> After enabling X.509 authentication, ensure that clients trust the broker's server certificate by having the *server-side* CA certificate in their trust store. Don't confuse trusting the *server-side* CA certificate with the *client-side* CA certificate used for client authentication that is specified in the `trustedClientCaCert` field.
+>
+> For a full example, see [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md).
 
 ### Connect mosquitto client to MQTT broker with X.509 client certificate
 
 A client like mosquitto needs two files to be able to connect to MQTT broker with TLS and X.509 client authentication.
 - The `--cert` parameter specifies the client certificate PEM file. This file should also include any intermediate certificates to help the MQTT broker build the complete certificate chain.
 - The `--key` parameter specifies the client private key PEM file.
 
-In cases where MQTT broker is using a self-signed CA certificate to issue its TLS server certificate, the `--cafile` parameter is needed. This file contains the CA certificate which the mosquitto client uses to validate the broker's server certificate when connecting over TLS. If the issuer of MQTT broker's server certificate is part of the system root store (such as well-known public CAs), the `--cafile` parameter can be omitted.
+In cases where MQTT broker is using a self-signed CA certificate to issue its TLS server certificate, the `--cafile` parameter is needed. This file contains the CA certificate (also known as *trust bundle*) which the mosquitto client uses to validate the broker's server certificate when connecting over TLS. If the issuer of MQTT broker's server certificate is part of the system root store (such as well-known public CAs), the `--cafile` parameter can be omitted.
 
 For example:
 
@@ -648,15 +662,36 @@ The broker verifies tokens using the [Kubernetes Token Review API](https://kuber
 
 ### Create a service account
 
-To create SATs, first create a service account. The following command creates a service account called `mqtt-client`.
+To create SATs, first [create a service account](https://kubernetes.io/docs/concepts/security/service-accounts/). The following command creates a service account called `mqtt-client`.
 
 ```bash
 kubectl create serviceaccount mqtt-client -n azure-iot-operations
 ```
 
-### Add attributes for authorization
+### Optional: Add attributes for authorization
+
+Clients authenticating via SAT can optionally have their service accounts annotated with attributes to be used with authorization policies. To distinguish these annotations from others, they begin with `aio-broker-auth/` prefix. 
+
+You can annotate a service account using `kubectl annotate`:
+
+```bash
+kubectl annotate serviceaccount <SERVICE_ACCOUNT_NAME> aio-broker-auth/<ATTRIBUTE>=<VALUE> -n azure-iot-operations
+```
+
+Or you can add the annotations to the service account manifest file:
+
+```yaml
+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>
+```
 
-Clients authenticating via SAT can optionally have their service accounts annotated with attributes to be used with authorization policies. To learn more, see [Authorize clients that use Kubernetes Service Account Tokens](./howto-configure-authentication.md).
+To learn more, see [Authorize clients that use Kubernetes Service Account Tokens](./howto-configure-authorization.md#authorize-clients-that-use-kubernetes-service-account-tokens).
 
 ### Enable Service Account Token (SAT) authentication
 
@@ -665,7 +700,7 @@ Modify the `authenticationMethods` setting in a *BrokerAuthentication* resource
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authentication** tab.
 1. Choose an existing authentication policy or create a new one.
 1. Add a new method by selecting **Add method**.
@@ -822,7 +857,7 @@ For testing, you can disable authentication for a broker listener port. Disablin
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the broker listener you want to edit from the list.
 1. On the port you want to disable authentication, select **None** in the authentication dropdown.
 
@@ -859,3 +894,4 @@ Successful reauthentication updates the client's credential expiry with the expi
 
 - About [BrokerListener resource](howto-configure-brokerlistener.md)
 - [Configure authorization for a BrokerListener](./howto-configure-authorization.md)
+- [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md)

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

@@ -37,7 +37,7 @@ The following example shows how to create a *BrokerAuthorization* resource using
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the **Authorization** tab.
 1. Choose an existing authentication policy or create a new one by selecting **Create authorization policy**.
 
@@ -333,7 +333,7 @@ For example, if a client has a certificate with subject `CN = smart-lock`, its u
 
 ## Authorize clients that use Kubernetes Service Account Tokens
 
-Authorization attributes for SATs are set as part of the Service Account annotations. For example, to add an authorization attribute named `group` with value `authz-sat`, run the command:
+Authorization attributes for SATs are set as part of the [Service Account annotations](./howto-configure-authentication.md#kubernetes-service-account-tokens). For example, to add an authorization attribute named `group` with value `authz-sat`, run the command:
 
 ```bash
 kubectl annotate serviceaccount mqtt-client aio-broker-auth/group=authz-sat
@@ -764,7 +764,7 @@ kubectl edit brokerauthorization my-authz-policies
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select the broker listener you want to edit from the list.
 1. On the port you want to disable authorization, select **None** in the authorization dropdown.
 
@@ -786,3 +786,4 @@ With MQTT 3.1.1, when a publish is denied, the client receives the PUBACK with n
 
 - About [BrokerListener resource](howto-configure-brokerlistener.md)
 - [Configure authentication for a BrokerListener](./howto-configure-authentication.md)
+- [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md)

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

@@ -51,7 +51,7 @@ To view or edit the default listener:
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 
     :::image type="content" source="media/howto-configure-brokerlistener/configure-broker-listener.png" alt-text="Screenshot using Azure portal to view Azure IoT Operations MQTT configuration.":::
 
@@ -202,7 +202,7 @@ This example shows how to create a new listener with load balancer service type.
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select **MQTT broker listener for LoadBalancer** > **Create**.
 
     Enter the following settings:
@@ -537,7 +537,7 @@ The following is an example of a BrokerListener resource that enables TLS on por
 # [Portal](#tab/portal)
 
 1. In the Azure portal, go to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 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.
 1. You can add TLS settings to the listener by selecting the **TLS** on an existing port or by adding a new port.
 
@@ -751,7 +751,7 @@ The following is an example of a BrokerListener resource that enables TLS on por
 # [Portal](#tab/portal)
 
 1. In the Azure portal, navigate to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 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`.
 1. You can add TLS settings to the listener by selecting the **TLS** on an existing port or by adding a new port.
 
@@ -921,3 +921,4 @@ From here, follow the same steps as previously to create a server certificate wi
 
 - [Configure MQTT broker authorization](howto-configure-authorization.md)
 - [Configure MQTT broker authentication](howto-configure-authentication.md)
+- [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md)

articles/iot-operations/manage-mqtt-broker/howto-test-connection.md

@@ -154,7 +154,7 @@ For example, to create a new broker listener with node port service type, servic
 # [Portal](#tab/portal)
 
 1. In the Azure portal, go to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select **MQTT broker listener for NodePort** > **Create**. 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.
 
     > [!CAUTION]
@@ -314,7 +314,7 @@ For example, to create a new broker listener with load balancer service type, se
 # [Portal](#tab/portal)
 
 1. In the Azure portal, go to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select **MQTT broker listener for NodePort** > **Create**. 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.
 
     > [!CAUTION]
@@ -521,7 +521,7 @@ The reason that MQTT broker uses TLS and service accounts authentication by defa
 # [Portal](#tab/portal)
 
 1. In the Azure portal, go to your IoT Operations instance.
-1. Under **Azure IoT Operations resources**, select **MQTT Broker**.
+1. Under **Components**, select **MQTT Broker**.
 1. Select **MQTT broker listener for NodePort** or **MQTT broker listener for LoadBalancer** > **Create**. 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.
 
     > [!CAUTION]
@@ -615,3 +615,4 @@ spec:
 
 - [Configure TLS with manual certificate management to secure MQTT communication](howto-configure-tls-manual.md)
 - [Configure authentication](howto-configure-authentication.md)
+- [Tutorial: TLS, X.509 client authentication, and attribute-based access control (ABAC) authorization](./tutorial-tls-x509.md)