+* <a name="no-downtime"></a> Azure NetApp Files supports a non-disruptive upgrade to Standard network features and a revert to Basic network features. This operation is expected to take at least 25 minutes. You can't create a regular or data protection volume or application volume group while the edit network feature operation is underway. This feature is currently in **preview** in the Australia East, Central India, East Asia, North Central US, and Switzerland North regions. In all other regions, updating network features can cause a network disruption on the volumes for up to 5 minutes.

+ This feature is currently in preview in the Australia East, Central India, East Asia, North Central US, and Switzerland North regions.

+ Title: Learn how to configure Azure Storage to de-identify documents with the de-identification service

+description: "Learn how to configure Azure Storage to de-identify documents with the de-identification service."

+#customer intent: As an IT admin, I want to know how to configure an Azure Storage account to allow access to the de-identification service to de-identify documents.

+# Tutorial: Configure Azure Storage to de-identify documents

+The Azure Health Data Services de-identification service (preview) can de-identify documents in Azure Storage via an asynchronous job. If you have many documents that you would like

+to de-identify, using a job is a good option. Jobs also provide consistent surrogation, meaning that surrogate values in the de-identified output will match across

+all documents. For more information about de-identification, including consistent surrogation, see [What is the de-identification service (preview)?](overview.md)

+When you choose to store documents in Azure Blob Storage, you're charged based on Azure Storage pricing. This cost isn't included in the

+ de-identification service pricing. [Explore Azure Blob Storage pricing](https://azure.microsoft.com/pricing/details/storage/blobs).

+In this tutorial, you:

+> [!div class="checklist"]

+> * Create a storage account and container

+> * Upload a sample document

+> * Grant the de-identification service access

+> * Configure network isolation

+## Prerequisites

+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* A de-identification service with system-assigned managed identity. [Deploy the de-identification service (preview)](quickstart.md).

+## Open Azure CLI

+Install [Azure CLI](/cli/azure/install-azure-cli) and open your terminal of choice. In this tutorial, we're using PowerShell.

+## Create a storage account and container

+1. Set your context, substituting the subscription name containing your de-identification service for the `<subscription_name>` placeholder:

+ ```powershell

+ az account set --subscription "<subscription_name>"

+ ```

+1. Save a variable for the resource group, substituting the resource group containing your de-identification service for the `<resource_group>` placeholder:

+ ```powershell

+ $ResourceGroup = "<resource_group>"

+ ```

+1. Create a storage account, providing a value for the `<storage_account_name>` placeholder:

+ ```powershell

+ $StorageAccountName = "<storage_account_name>"

+ $StorageAccountId = $(az storage account create --name $StorageAccountName --resource-group $ResourceGroup --sku Standard_LRS --kind StorageV2 --min-tls-version TLS1_2 --allow-blob-public-access false --query id --output tsv)

+ ```

+1. Assign yourself a role to perform data operations on the storage account:

+ ```powershell

+ $UserId = $(az ad signed-in-user show --query id -o tsv)

+ az role assignment create --role "Storage Blob Data Contributor" --assignee $UserId --scope $StorageAccountId

+ ```

+1. Create a container to hold your sample document:

+ ```powershell

+ az storage container create --account-name $StorageAccountName --name deidtest --auth-mode login

+ ```

+## Upload a sample document

+Next, you upload a document that contains synthetic PHI:

+```powershell

+$DocumentContent = "The patient came in for a visit on 10/12/2023 and was seen again November 4th at Contoso Hospital."

+az storage blob upload --data $DocumentContent --account-name $StorageAccountName --container-name deidtest --name deidsample.txt --auth-mode login

+```

+## Grant the de-identification service access to the storage account

+In this step, you grant the de-identification service's system-assigned managed identity role-based access to the container. You grant the **Storage Blob

+Data Contributor** role because the de-identification service will both read the original document and write de-identified output documents. Substitute the name of

+your de-identification service for the `<deid_service_name>` placeholder:

+```powershell

+$DeidServicePrincipalId=$(az resource show -n <deid_service_name> -g $ResourceGroup --resource-type microsoft.healthdataaiservices/deidservices --query identity.principalId --output tsv)

+az role assignment create --assignee $DeidServicePrincipalId --role "Storage Blob Data Contributor" --scope $StorageAccountId

+```

+## Configure network isolation on the storage account

+Next, you update the storage account to disable public network access and only allow access from trusted Azure services such as the de-identification service.

+After running this command, you won't be able to view the storage container contents without setting a network exception.

+Learn more at [Configure Azure Storage firewalls and virtual networks](/azure/storage/common/storage-network-security).

+```powershell

+az storage account update --name $StorageAccountName --public-network-access Disabled --bypass AzureServices

+```

+## Clean up resources

+Once you're done with the storage account, you can delete the storage account and role assignments:

+```powershell

+az role assignment delete --assignee $DeidServicePrincipalId --role "Storage Blob Data Contributor" --scope $StorageAccountId

+az role assignment delete --assignee $UserId --role "Storage Blob Data Contributor" --scope $StorageAccountId

+az storage account delete --ids $StorageAccountId --yes

+```

+## Next step

+> [!div class="nextstepaction"]

+> [Quickstart: Azure Health De-identification client library for .NET](quickstart-sdk-net.md)

+> [!div class="nextstepaction"]

+> [Tutorial: Configure Azure Storage to de-identify documents](configure-storage.md)

+Azure IoT Operations Preview deploys a default *BrokerAuthentication* resource named `default` linked with the *default* listener in the `azure-iot-operations` namespace. It's configured to only use Kubernetes Service Account Tokens (SATs) for authentication.

+> [!IMPORTANT]

+> The service account token (SAT) authentication method in the default *BrokerAuthentication* resource is required for components in the Azure IoT Operations to function correctly. Avoid updating or deleting the default *BrokerAuthentication* resource.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, select **MQTT Broker**.

+1. Select the **Authentication** tab.

+1. From authentication policy list, select the **default** policy name.

+ :::image type="content" source="media/howto-configure-authentication/authentication-policy-default.png" alt-text="Screenshot using Azure portal to view the default MQTT broker authentication policy.":::

+To add new authentication methods, select **Add method**.

+# [Bicep](#tab/bicep)

+To edit the default endpoint, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource defaultBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: 'default'

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authenticationMethods: [

+ {

+ method: 'ServiceAccountToken'

+ serviceAccountTokenSettings: {

+ audiences: [

+ 'aio-internal'

+ ]

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+To inspect the default broker authentication resource, run:

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

+ name: default

+If you need to make changes, modify the `authenticationMethods` field in this resource while retaining the SAT authentication method with the `aio-internal` audience. Then, deploy it using `kubectl apply`.

+ name: default

+## Configure authentication method

+You can add authentication methods such as X.509, SAT, or custom to authentication policies.

+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. Select the **Authentication** tab.

+1. Choose an existing authentication policy or create a new one.

+1. Add a new method by selecting **Add method**.

+1. Choose the method type from the dropdown list then select **Add details** to configure the method.

+ :::image type="content" source="media/howto-configure-authentication/create-authentication-policy.png" alt-text="Screenshot using the Azure portal to add an MQTT broker authentication policy method.":::

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-09-15-preview' = {

+ 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: {

+ 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'

+ }

+ }

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+Modify the *BrokerAuthentication* resource for an authentication policy by adding new methods to the `authenticationMethods` section. The following example shows multiple authentication methods for a *BrokerAuthentication* resource:

+```yaml

+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1

+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:

+ authorizationAttributes:

+ trustedClientCaCert: client-ca

+ 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

+```

+To change the configuration, modify the `authenticationMethods` setting in this *BrokerAuthentication* resource then deploy it using `kubectl apply`.

+### X.509

+Once the trusted client root CA certificate and the certificate-to-attribute mapping are imported, enable X.509 client authentication by adding it as one of the authentication methods as part of a *BrokerAuthentication* resource linked to a TLS-enabled listener.

+#### Certificate attributes for authorization

+X.509 attributes can be specified in the *BrokerAuthentication* resource, and they're used to authorize clients based on their certificate properties. The attributes are defined in the `authorizationAttributes` field.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, 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**.

+1. Choose the method type **X.509** from the dropdown list then select **Add details** to configure the method.

+ :::image type="content" source="media/howto-configure-authentication/x509-method.png" alt-text="Screenshot using Azure portal to set MQTT broker X.509 authentication method.":::

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: policyName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authenticationMethods: [

+ {

+ method: 'X509'

+ x509Settings: {

+ 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'

+ }

+ }

+ }

+ }

+ }

+ ]

+ }

+}

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+#### Connect mosquitto client to MQTT broker with X.509 client certificate

+#### Understand MQTT broker X.509 client authentication flow

+### Kubernetes Service Account Tokens

+#### Create a service account

+#### Add attributes for authorization

+#### Enable Service Account Token (SAT) 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. Select the **Authentication** tab.

+1. Choose an existing authentication policy or create a new one.

+1. Add a new method by selecting **Add method**.

+1. Choose the method type **Kubernetes SAT** from the dropdown list then select **Add details** to configure the method.

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: policyName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authenticationMethods: [

+ {

+ method: 'ServiceAccountToken'

+ serviceAccountTokenSettings: {

+ audiences: [

+ 'aio-internal'

+ 'my-audience'

+ ]

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+ - aio-internal

+ - my-audience

+#### Test SAT authentication

+#### Refresh service account tokens

+ secretRef: custom-auth-client-cert

+## Disable authentication

+For testing, you can disable authentication for a broker listener port. Disabling authentication isn't recommended for production environments.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, 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.

+# [Bicep](#tab/bicep)

+To disable authentication, omit the `authenticationRef` in the `ports` setting of your *BrokerListener* resource.

+# [Kubernetes](#tab/kubernetes)

+To disable authentication, omit the `authenticationRef` in the `ports` setting of your *BrokerListener* resource.

+MQTT v5 clients authenticated with SATs and custom authentication can reauthenticate with a new credential before their initial credential expires. X.509 clients can't reauthenticate and must re-establish the connection since authentication is done at the TLS layer.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, select **MQTT Broker**.

+1. Select the **Authorization** tab.

+1. Choose an existing authentication policy or create a new one by selecting **Create authorization policy**.

+ :::image type="content" source="media/howto-configure-authorization/authorization-rules.png" alt-text="Screenshot using Azure portal to create broker authorization rules.":::

+# [Bicep](#tab/bicep)

+To edit the default endpoint, create a Bicep `.bicep` file with the following content. Update the settings as needed, and replace the placeholder values like `<AIO_INSTANCE_NAME>` with your own.

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: policyName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authorizationPolicies: {

+ cache: 'Enabled'

+ rules: [

+ {

+ principals: {

+ usernames: [

+ 'temperature-sensor'

+ 'humidity-sensor'

+ ]

+ attributes: [

+ {

+ city: 'seattle'

+ organization: 'contoso'

+ }

+ ]

+ }

+ brokerResources: [

+ {

+ method: 'Connect'

+ }

+ {

+ method: 'Publish'

+ topics: [

+ '/telemetry/{principal.username}'

+ '/telemetry/{principal.attributes.organization}'

+ ]

+ }

+ {

+ method: 'Subscribe'

+ topics: [

+ '/commands/{principal.attributes.organization}'

+ ]

+ }

+ ]

+ }

+ ]

+ }

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+To create this *BrokerAuthorization* resource, apply the YAML manifest to your Kubernetes cluster.

+# [Portal](#tab/portal)

+In the **Broker authorization details** for your authorization policy, use the following configuration:

+```json

+[

+ {

+ "brokerResources": [

+ {

+ "clientIds": [

+ "{principal.attributes.building}*"

+ ],

+ "method": "Connect",

+ "topics": []

+ },

+ {

+ "clientIds": [],

+ "method": "Publish",

+ "topics": [

+ "sensors/{principal.attributes.building}/{principal.clientId}/telemetry"

+ ]

+ }

+ ],

+ "principals": {

+ "attributes": [

+ {

+ "building": "building22"

+ },

+ {

+ "building": "building23"

+ }

+ ]

+ }

+ }

+]

+```

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: policyName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authorizationPolicies: {

+ cache: 'Enabled'

+ rules: [

+ {

+ principals: {

+ attributes: [

+ {

+ building: 'building22'

+ }

+ {

+ building: 'building23'

+ }

+ ]

+ }

+ brokerResources: [

+ {

+ method: 'Connect'

+ clientIds: [

+ '{principal.attributes.building}*' // client IDs must start with building22

+ ]

+ }

+ {

+ method: 'Publish'

+ topics: [

+ 'sensors/{principal.attributes.building}/{principal.clientId}/telemetry'

+ ]

+ }

+ ]

+ }

+ ]

+ }

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+Here, if the `clientIds` weren't set under the `Connect` method, a client with any client ID could connect as long as it had the `building` attribute set to `building22` or `building23`. By adding the `clientIds` field, only clients with client IDs that start with `building22` or `building23` can connect. This ensures not only that the client has the correct attribute but also that the client ID matches the expected pattern.

+# [Portal](#tab/portal)

+In the **Broker authorization details** for your authorization policy, use the following configuration:

+```json

+[

+ {

+ "brokerResources": [

+ {

+ "clientIds": [],

+ "method": "Connect",

+ "topics": []

+ },

+ {

+ "clientIds": [],

+ "method": "Publish",

+ "topics": [

+ "odd-numbered-orders"

+ ]

+ },

+ {

+ "clientIds": [],

+ "method": "Subscribe",

+ "topics": [

+ "orders"

+ ]

+ }

+ ],

+ "principals": {

+ "attributes": [

+ {

+ "group": "authz-sat"

+ }

+ ]

+ }

+ }

+]

+```

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param policyName string = '<POLICY_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: policyName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ authorizationPolicies: {

+ rules: [

+ {

+ principals: {

+ attributes: [

+ {

+ group: 'authz-sat'

+ }

+ ]

+ }

+ brokerResources: [

+ {

+ method: 'Connect'

+ }

+ {

+ method: 'Publish'

+ topics: [

+ 'odd-numbered-orders'

+ ]

+ }

+ {

+ method: 'Subscribe'

+ topics: [

+ 'orders'

+ ]

+ }

+ ]

+ }

+ ]

+ }

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, 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.

+# [Bicep](#tab/bicep)

+To disable authorization, omit `authorizationRef` in the `ports` setting of your *BrokerListener* resource.

+# [Kubernetes](#tab/kubernetes)

+To disable authorization, omit `authorizationRef` in the `ports` setting of your *BrokerListener* resource.

+To configure the scaling settings MQTT broker, you need to specify the `cardinality` fields in the specification of the *Broker* custom resource. For more information on setting the mode and cardinality settings using Azure CLI, see [az iot ops create](/cli/azure/iot/ops#az-iot-ops-create).

+To configure the memory profile settings MQTT broker, specify the `memoryProfile` fields in the spec of the *Broker* custom resource. For more information on setting the memory profile setting using Azure CLI, see [az iot ops create](/cli/azure/iot/ops#az-iot-ops-create).

+ name: default

+- You can have up to three listeners. One listener per service type of `loadBalancer`, `clusterIp`, or `nodePort`. The default *BrokerListener* named *default* is service type `clusterIp`.

+- Ports can't conflict over different listeners

+When you deploy Azure IoT Operations Preview, the deployment also creates a *BrokerListener* resource named `default` in the `azure-iot-operations` namespace. This listener is linked to the default *Broker* resource named `default` that's also created during deployment. The default listener exposes the broker on port 18883 with TLS and SAT authentication enabled. The TLS certificate is [automatically managed](#configure-tls-with-automatic-certificate-management) by cert-manager. Authorization is disabled by default.

+# [Bicep](#tab/bicep)

+You shouldn't modify the default listener using Bicep. Instead, create a new listener and configure it as needed.

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

+ name: default

+ - authenticationRef: default

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

+ | TLS | Indicates whether TLS is enabled for secure communication. Can be set to [automatic](#configure-tls-with-automatic-certificate-management) or [manual](#configure-tls-with-manual-certificate-management). |

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param listenerServiceName string = '<LISTENER_SERVICE_NAME>'

+param listenerName string = '<LISTENER_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: listenerName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ serviceName: listenerServiceName

+ serviceType: 'LoadBalancer'

+ ports: [

+ {

+ authenticationRef: 'default'

+ port: 18883

+ protocol: 'Mqtt'

+ tls: {

+ certManagerCertificateSpec: {

+ issuerRef: {

+ group: 'cert-manager.io'

+ kind: 'Issuer'

+ name: 'mq-dmqtt-frontend'

+ }

+ }

+ mode: 'Automatic'

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+ authenticationRef: default

+For more information about authentication, see [Configure MQTT broker authentication](howto-configure-authentication.md). For more information about authorization, see [Configure MQTT broker authorization](howto-configure-authorization.md). For more information about TLS, see [Configure TLS with automatic certificate management](#configure-tls-with-automatic-certificate-management) or [Configure TLS with manual certificate management](#configure-tls-with-manual-certificate-management) sections.

+## Configure TLS with automatic certificate management

+To enable TLS with automatic certificate management, specify the TLS settings on a listener port.

+### Verify cert-manager installation

+With automatic certificate management, you use cert-manager to manage the TLS server certificate. By default, cert-manager is installed alongside Azure IoT Operations Preview in the `azure-iot-operations` namespace already. Verify the installation before proceeding.

+1. Use `kubectl` to check for the pods matching the cert-manager app labels.

+ ```bash

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

+ ```

+

+ ```Output

+ 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

+ ```

+1. If you see the pods shown as ready and running, cert-manager is installed and ready to use.

+> [!TIP]

+> To further verify the installation, check the cert-manager documentation [verify installation](https://cert-manager.io/docs/installation/kubernetes/#verifying-the-installation). Remember to use the `azure-iot-operations` namespace.

+### Create an Issuer for the TLS server certificate

+The cert-manager *Issuer* resource defines how certificates are automatically issued. Cert-manager [supports several Issuers types natively](https://cert-manager.io/docs/configuration/). It also supports an [external](https://cert-manager.io/docs/configuration/external/) issuer type for extending functionality beyond the natively supported issuers. MQTT broker can be used with any type of cert-manager issuer.

+> [!IMPORTANT]

+> During initial deployment, Azure IoT Operations is installed with a default Issuer for TLS server certificates. You can use this issuer for development and testing. For more information, see [Default root CA and issuer with Azure IoT Operations](#default-root-ca-and-issuer). The steps below are only required if you want to use a different issuer.

+The approach to create the issuer is different depending on your scenario. The following sections list examples to help you get started.

+# [Development or test](#tab/test)

+The CA issuer is useful for development and testing. It must be configured with a certificate and private key stored in a Kubernetes secret.

+#### Set up the root certificate as a Kubernetes secret

+If you have an existing CA certificate, create a Kubernetes secret with the CA certificate and private key PEM files. Run the following command and you have set up the root certificate as a Kubernetes secret and can skip the next section.

+```bash

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

+```

+If you don't have a CA certificate, cert-manager can generate a root CA certificate for you. Using cert-manager to generate a root CA certificate is known as [bootstrapping](https://cert-manager.io/docs/configuration/selfsigned/#bootstrapping-ca-issuers) a CA issuer with a self-signed certificate.

+1. Start by creating `ca.yaml`:

+ ```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

+ ```

+1. Create the self-signed CA certificate with the following command:

+ ```bash

+ kubectl apply -f ca.yaml

+ ```

+Cert-manager creates a CA certificate using its defaults. The properties of this certificate can be changed by modifying the Certificate specification. See [cert-manager documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec) for a list of valid options.

+#### Distribute the root certificate

+The prior example stores the CA certificate in a Kubernetes secret called `test-ca`. The certificate in PEM format can be retrieved from the secret and stored in a file `ca.crt` with the following command:

+```bash

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

+```

+This certificate must be distributed and trusted by all clients. For example, use `--cafile` flag for a mosquitto client.

+#### Create issuer based on CA certificate

+Cert-manager needs an issuer based on the CA certificate generated or imported in the earlier step. Create the following file as `issuer-ca.yaml`:

+```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

+```

+Create the issuer with the following command:

+```bash

+kubectl apply -f issuer-ca.yaml

+```

+The prior command creates an issuer for issuing the TLS server certificates. Note the name and kind of the issuer. In the example, name `my-issuer` and kind `Issuer`. These values are set in the BrokerListener resource later.

+# [Production](#tab/prod)

+For production, check cert-manager documentation to see which issuer works best for you. For example, with [Vault Issuer](https://developer.hashicorp.com/vault/tutorials/kubernetes/kubernetes-cert-manager):

+1. Deploy the vault in an environment of choice, like [Kubernetes](https://developer.hashicorp.com/vault/tutorials/kubernetes/kubernetes-raft-deployment-guide). Initialize and unseal the vault accordingly.

+1. Create and configure the PKI secrets engine by importing your CA certificate.

+1. Configure vault with role and policy for issuing server certificates.

+ The following is an example role. Note `ExtKeyUsageServerAuth` makes the server certificate work:

+ ```bash

+ vault write pki/roles/my-issuer \

+ allow_any_name=true \

+ client_flag=false \

+ ext_key_usage=ExtKeyUsageServerAuth \

+ no_store=true \

+ max_ttl=240h

+ ```

+ Example policy for the role:

+ ```hcl

+ path "pki/sign/my-issuer" {

+ capabilities = ["create", "update"]

+ }

+ ```

+1. Set up authentication between cert-manager and vault using a method of choice, like [SAT](https://developer.hashicorp.com/vault/docs/auth/kubernetes).

+1. [Configure the cert-manager Vault Issuer](https://cert-manager.io/docs/configuration/vault/).

+### Enable TLS automatic certificate management for a port

+The following is an example of a BrokerListener resource that enables TLS on port 8884 with automatic certificate management.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, 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.

+ :::image type="content" source="media/howto-configure-brokerlistener/tls-auto.png" alt-text="Screenshot using Azure portal to create MQTT broker for load balancer listener with automatic TLS certificates." lightbox="media/howto-configure-brokerlistener/tls-auto.png":::

+ Enter the following settings:

+ | Setting | Description |

+ | -- | |

+ | Port | Port number on which the BrokerListener listens for MQTT connections. Required. |

+ | Authentication | The [authentication resource reference](howto-configure-authentication.md). |

+ | Authorization | The [authorization resource reference](howto-configure-authorization.md). |

+ | TLS | Select the *Add* button. |

+ | Issuer name | Name of the cert-manager issuer. Required. |

+ | Issuer kind | Kind of the cert-manager issuer. Required. |

+ | Issuer group | Group of the cert-manager issuer. Required. |

+ | Private key algorithm | Algorithm for the private key. |

+ | Private key rotation policy | Policy for rotating the private key. |

+ | DNS names | DNS subject alternate names for the certificate. |

+ | IP addresses | IP addresses of the subject alternate names for the certificate. |

+ | Secret name | Kubernetes secret containing an X.509 client certificate. |

+ | Duration | Total lifetime of the TLS server certificate Defaults to 90 days. |

+ | Renew before | When to begin renewing the certificate. |

+1. Select **Save** to save the TLS settings.

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param listenerServiceName string = '<LISTENER_SERVICE_NAME>'

+param listenerName string = '<LISTENER_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: listenerName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ serviceName: listenerServiceName

+ serviceType: 'LoadBalancer'

+ ports: [

+ {

+ authenticationRef: 'default'

+ port: 8884

+ tls: {

+ mode: 'Manual'

+ manual: {

+ secretRef: 'server-cert-secret'

+ }

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+#### Optional: Configure server certificate parameters

+The only required parameters are `issuerRef.name` and `issuerRef.kind`. All properties of the generated TLS server certificates are automatically chosen. However, MQTT broker allows certain properties to be customized by specifying them in the BrokerListener resource, under `tls.automatic.issuerRef`. The following is an example of all supported properties:

+```bicep

+ ports: [

+ {

+ port: 8884

+ tls: {

+ mode: 'Automatic'

+ certManagerCertificateSpec: {

+ issuerRef: {

+ // Name of issuer. Required.

+ name: 'my-issuer'

+ // 'Issuer' or 'ClusterIssuer'. Required.

+ kind: 'Issuer'

+ // Issuer group. Optional; defaults to 'cert-manager.io'.

+ // External issuers may use other groups.

+ group: 'cert-manager.io'

+ }

+ // Namespace of certificate. Optional; omit to use default namespace.

+ namespace: 'az'

+ // Where to store the generated TLS server certificate. Any existing

+ // data at the provided secret will be overwritten.

+ // Optional; defaults to 'my-issuer-{port}'.

+ secret: 'my-issuer-8884'

+ // Parameters for the server certificate's private key.

+ // Optional; defaults to rotationPolicy: Always, algorithm: ECDSA, size: 256.

+ privateKey: {

+ rotationPolicy: 'Always'

+ algorithm: 'ECDSA'

+ size: 256

+ }

+ // Total lifetime of the TLS server certificate. Optional; defaults to '720h' (30 days).

+ duration: '720h'

+ // When to begin renewing the certificate. Optional; defaults to '240h' (10 days).

+ renewBefore: '240h'

+ // Any additional SANs to add to the server certificate. Omit if not required.

+ san: {

+ dns: [

+ 'iotmq.example.com'

+ // To connect to the broker from a different namespace, add the following DNS name:

+ 'aio-broker.azure-iot-operations.svc.cluster.local'

+ ]

+ ip: [

+ '192.168.1.1'

+ ]

+ }

+ }

+ }

+ }

+ ]

+```

+# [Kubernetes](#tab/kubernetes)

+Modify the `tls` setting in a BrokerListener resource to specify a TLS port and *Issuer* for the frontends.

+```yaml

+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1

+kind: BrokerListener

+metadata:

+ name: loadbalancer-tls

+ namespace: azure-iot-operations

+spec:

+ brokerRef: default

+ serviceType: loadBalancer

+ serviceName: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'

+ ports:

+ - port: 8884 # Avoid conflicts with default port 18883

+ tls:

+ mode: Automatic

+ certManagerCertificateSpec:

+ issuerRef:

+ name: my-issuer

+ kind: Issuer

+```

+Once the BrokerListener resource is configured, MQTT broker automatically creates a new service with the specified port and TLS enabled.

+#### Optional: Configure server certificate parameters

+The only required parameters are `issuerRef.name` and `issuerRef.kind`. All properties of the generated TLS server certificates are automatically chosen. However, MQTT broker allows certain properties to be customized by specifying them in the BrokerListener resource, under `tls.automatic.issuerRef`. The following is an example of all supported properties:

+```yaml

+# cert-manager issuer for TLS server certificate. Required.

+issuerRef:

+ # Name of issuer. Required.

+ name: my-issuer

+ # 'Issuer' or 'ClusterIssuer'. Required.

+ kind: Issuer

+ # Issuer group. Optional; defaults to 'cert-manager.io'.

+ # External issuers may use other groups.

+ group: cert-manager.io

+# Namespace of certificate. Optional; omit to use default namespace.

+namespace: az

+# Where to store the generated TLS server certificate. Any existing

+# data at the provided secret will be overwritten.

+# Optional; defaults to 'my-issuer-{port}'.

+secret: my-issuer-8884

+# Parameters for the server certificate's private key.

+# Optional; defaults to rotationPolicy: Always, algorithm: ECDSA, size: 256.

+privateKey:

+ rotationPolicy: Always

+ algorithm: ECDSA

+ size: 256

+# Total lifetime of the TLS server certificate. Optional; defaults to '720h' (30 days).

+duration: 720h

+# When to begin renewing the certificate. Optional; defaults to '240h' (10 days).

+renewBefore: 240h

+# Any additional SANs to add to the server certificate. Omit if not required.

+san:

+ dns:

+ - iotmq.example.com

+ # To connect to the broker from a different namespace, add the following DNS name:

+ - aio-broker.azure-iot-operations.svc.cluster.local

+ ip:

+ - 192.168.1.1

+```

+#### Verify deployment

+Use kubectl to check that the service associated with the BrokerListener resource is running. From the example above, the service name is `my-new-tls-listener` and the namespace is `azure-iot-operations`. The following command checks the service status:

+```console

+$ kubectl get service my-new-tls-listener -n azure-iot-operations

+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+my-new-tls-listener LoadBalancer 10.X.X.X 172.X.X.X 8884:32457/TCP 33s

+```

+#### Connect to the broker with TLS

+Once the server certificate is configured, TLS is enabled. To test with mosquitto:

+```bash

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

+```

+The `--cafile` argument enables TLS on the mosquitto client and specifies that the client should trust all server certificates issued by the given file. You must specify a file that contains the issuer of the configured TLS server certificate.

+Replace `$HOST` with the appropriate host:

+- If connecting from [within the same cluster](howto-test-connection.md#connect-to-the-default-listener-inside-the-cluster), replace with the service name given (`my-new-tls-listener` in example) or the service `CLUSTER-IP`.

+- If connecting from outside the cluster, the service `EXTERNAL-IP`.

+Remember to specify authentication methods if needed.

+### Default root CA and issuer

+To help you get started, Azure IoT Operations is deployed with a default "quickstart" root CA and issuer for TLS server certificates. You can use this issuer for development and testing. For more information, see [Default root CA and issuer for TLS server certificates](../deploy-iot-ops/concept-default-root-ca.md).

+For production, you must configure a CA issuer with a certificate from a trusted CA, as described in the previous sections.

+## Configure TLS with manual certificate management

+To manually configure MQTT broker to use a specific TLS certificate, specify it in a BrokerListener resource with a reference to a Kubernetes secret. Then deploy it using kubectl. This article shows an example to configure TLS with self-signed certificates for testing.

+### Create certificate authority with Step CLI

+[Step](https://smallstep.com/) is a certificate manager that can quickly get you up and running when creating and managing your own private CA.

+1. [Install Step CLI](https://smallstep.com/docs/step-cli/installation/) and create a root certificate authority (CA) certificate and key.

+ ```bash

+ step certificate create --profile root-ca "Example Root CA" root_ca.crt root_ca.key

+ ```

+1. Create an intermediate CA certificate and key signed by the root CA.

+ ```bash

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

+ --ca root_ca.crt --ca-key root_ca.key

+ ```

+### Create server certificate

+Use Step CLI to create a server certificate from the signed by the intermediate CA.

+```bash

+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

+```

+Here, `mqtts-endpoint` and `localhost` are the Subject Alternative Names (SANs) for MQTT broker's frontend in Kubernetes and local clients, respectively. To connect over the internet, add a `--san` with [an external IP](#use-external-ip-for-the-server-certificate). The `--no-password --insecure` flags are used for testing to skip password prompts and disable password protection for the private key because it's stored in a Kubernetes secret. For production, use a password and store the private key in a secure location like Azure Key Vault.

+#### Certificate key algorithm requirements

+Both EC and RSA keys are supported, but all certificates in the chain must use the same key algorithm. If you import your own CA certificates, ensure that the server certificate uses the same key algorithm as the CAs.

+### Import server certificate chain as a Kubernetes secret

+1. Create a full server certificate chain, where the order of the certificates matters: the server certificate is the first one in the file, the intermediate is the second.

+ ```bash

+ cat mqtts-endpoint.crt intermediate_ca.crt > server_chain.crt

+ ```

+1. Create a Kubernetes secret with the server certificate chain and server key using kubectl.

+ ```bash

+ kubectl create secret tls server-cert-secret -n azure-iot-operations \

+ --cert server_chain.crt \

+ --key mqtts-endpoint.key

+ ```

+### Enable TLS manual certificate management for a port

+The following is an example of a BrokerListener resource that enables TLS on port 8884 with manual certificate management.

+# [Portal](#tab/portal)

+1. In the Azure portal, navigate to your IoT Operations instance.

+1. Under **Azure IoT Operations resources**, 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.

+ :::image type="content" source="media/howto-configure-brokerlistener/tls-manual.png" alt-text="Screenshot using Azure portal to create MQTT broker for load balancer listener with manual TLS certificates." lightbox="media/howto-configure-brokerlistener/tls-manual.png":::

+ Enter the following settings:

+ | Setting | Description |

+ | -- | |

+ | Port | Port number on which the BrokerListener listens for MQTT connections. Required. |

+ | Authentication | The [authentication resource reference](howto-configure-authentication.md). |

+ | Authorization | The [authorization resource reference](howto-configure-authorization.md). |

+ | TLS | Select the *Add* button. |

+ | Secret name | Kubernetes secret containing an X.509 client certificate. |

+1. Select **Save** to save the TLS settings.

+# [Bicep](#tab/bicep)

+```bicep

+param aioInstanceName string = '<AIO_INSTANCE_NAME>'

+param customLocationName string = '<CUSTOM_LOCATION_NAME>'

+param listenerServiceName string = '<LISTENER_SERVICE_NAME>'

+param listenerName string = '<LISTENER_NAME>'

+resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {

+ name: aioInstanceName

+}

+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {

+ name: customLocationName

+}

+resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {

+ parent: aioInstance

+ name: 'default'

+}

+resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-09-15-preview' = {

+ parent: defaultBroker

+ name: listenerName

+ extendedLocation: {

+ name: customLocation.id

+ type: 'CustomLocation'

+ }

+ properties: {

+ serviceName: listenerServiceName

+ serviceType: 'LoadBalancer'

+ ports: [

+ {

+ authenticationRef: 'default'

+ port: 8885

+ tls: {

+ mode: 'Manual'

+ manual: {

+ secretRef: 'server-cert-secret'

+ }

+ }

+ }

+ ]

+ }

+}

+```

+Deploy the Bicep file using Azure CLI.

+```azurecli

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

+```

+# [Kubernetes](#tab/kubernetes)

+Modify the `tls` setting in a *BrokerListener* resource to specify manual TLS configuration referencing the Kubernetes secret. Note the name of the secret used for the TLS server certificate (`server-cert-secret` in the example previously).

+```yaml

+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1

+kind: BrokerListener

+metadata:

+ name: loadbalancer-tls

+ namespace: azure-iot-operations

+spec:

+ brokerRef: default

+ serviceType: loadBalancer # Optional, defaults to clusterIP

+ serviceName: aio-broker-loadbalancer-tls # 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

+```

+Once the *BrokerListener* resource is created, the operator automatically creates a Kubernetes service and deploys the listener. You can check the status of the service by running `kubectl get svc`.

+### Connect to the broker with TLS

+To test the TLS connection with mosquitto client, publish a message and pass the root CA certificate in the parameter `--cafile`.

+```bash

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

+```

+```Output

+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

+```

+> [!TIP]

+> To use localhost, the port must be available on the host machine. For example, `kubectl port-forward svc/mqtts-endpoint 8885:8885 -n azure-iot-operations`. With some Kubernetes distributions like K3d, you can add a forwarded port with `k3d cluster edit $CLUSTER_NAME --port-add 8885:8885@loadbalancer`.

+> [!NOTE]

+> To connect to the broker you need to distribute root of trust to the clients, also known as trust bundle. In this case the root of trust is the self-signed root CA created Step CLI. Distribution of root of trust is required for the client to verify the server certificate chain. If your MQTT clients are workloads on the Kubernetes cluster you also need to create a ConfigMap with the root CA and mount it in your Pod.

+Remember to specify username, password, etc. if MQTT broker authentication is enabled.

+#### Use external IP for the server certificate

+To connect with TLS over the internet, MQTT broker's server certificate must have its external hostname as a SAN. In production, this is usually a DNS name or a well-known IP address. However, during dev/test, you might not know what hostname or external IP is assigned before deployment. To solve this, deploy the listener without the server certificate first, then create the server certificate and secret with the external IP, and finally import the secret to the listener.

+If you try to deploy the example TLS listener `manual-tls-listener` but the referenced Kubernetes secret `server-cert-secret` doesn't exist, the associated service gets created, but the pods don't start. The service is created because the operator needs to reserve the external IP for the listener.

+```bash

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

+```

+```Output

+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+mqtts-endpoint LoadBalancer 10.X.X.X 172.X.X.X 8885:30674/TCP 1m15s

+```

+However, this behavior is expected and it's okay to leave it like this while we import the server certificate. The health manager logs mention MQTT broker is waiting for the server certificate.

+```bash

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

+```

+```Output

+...

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

+```

+> [!NOTE]

+> Generally, in a distributed system, pods logs aren't deterministic and should be used with caution. The right way for information like this to surface is through Kubernetes events and custom resource status, which is in the backlog. Consider the previous step as a temporary workaround.

+Even though the frontend pods aren't up, the external IP is already available.

+```bash

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

+```

+```Output

+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+mqtts-endpoint LoadBalancer 10.X.X.X 172.X.X.X 8885:30674/TCP 1m15s

+```

+From here, follow the same steps as previously to create a server certificate with this external IP in `--san` and create the Kubernetes secret in the same way. Once the secret is created, it's automatically imported to the listener.

+If you still have questions, [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade).

+For more information about Support plans, see [Azure Support plans](https://azure.microsoft.com/support/plans/response/).

+5. The servers should now be restored.

+If you still have questions, [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade).

+For more information about Support plans, see [Azure Support plans](https://azure.microsoft.com/support/plans/response/).

+The command retrieves the pvc from the pod and then deletes the `volumeattachment` object. It then deletes the pod. The pod later gets recreated on another node along with a successful volume attachment object.

+If you still have questions, [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade).

+For more information about Support plans, see [Azure Support plans](https://azure.microsoft.com/support/plans/response/).

+If you still have questions, [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade).

+For more information about Support plans, see [Azure Support plans](https://azure.microsoft.com/support/plans/response/).

+If you still have questions, [contact support](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade).

+For more information about Support plans, see [Azure Support plans](https://azure.microsoft.com/support/plans/response/).

+ Title: Troubleshoot container memory limits

+description: Troubleshooting Kubernetes container limits

+# Troubleshoot container memory limits

+## Alerting for memory limits

+It's recommended to have alerts set up for the Operator Nexus cluster to look for Kubernetes pods restarting from OOMKill errors. These alerts allow customers to know if a component on a server is working appropriately.

+Metrics exposed to identify memory limits:

+| Metric Name | Description |

+| | |

+| Container Restarts | `kube_pod_container_status_restarts_total` |

+| Container Status Terminated Reason | `kube_pod_container_status_terminated_reason` |

+| Container Resource Limits | `kube_pod_container_resource_limits` |

+`Container Status Terminated Reason` displays the OOMKill reason for impacted pods.

+## Identifying Out of Memory (OOM) pods

+Start by identifying any components that are restarting or show OOMKill.

+```azcli

+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \

+ --limit-time-seconds 60 \

+ --commands "[{command:'kubectl get',arguments:[pods,-n,nc-system]}]" \

+ --resource-group "<cluster_MRG>" \

+ --subscription "<subscription>"

+```

+Once identified, a `describe pod` command can determine the status and restart count.

+```azcli

+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \

+ --limit-time-seconds 60 \

+ --commands "[{command:'kubectl describe',arguments:[pod,<podName>,-n,nc-system]}]" \

+ --resource-group "<cluster_MRG>" \

+ --subscription "<subscription>"

+```

+At the same time, a `get events` command can provide history to see the frequency of pod restarts.

+```azcli

+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \

+ --limit-time-seconds 60 \

+ --commands "[{command:'kubectl get',arguments:[events,-n,nc-system,|,grep,<podName>]}]" \

+ --resource-group "<cluster_MRG>" \

+ --subscription "<subscription>"

+```

+The data from these commands identify whether a pod is restarting due to `OOMKill`.

+## Patching memory limits

+Raise a Microsoft support request for all memory limit changes for adjustments and support.

+> [!WARNING]

+> Patching memory limits to a pod are not permanent and can be overwritten if the pod restarts.

+## Confirm memory limit changes

+When memory limits change, the pods should return to `Ready` state and stop restarting.

+The following commands can be used to confirm the behavior.

+```azcli

+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \

+ --limit-time-seconds 60 \

+ --commands "[{command:'kubectl get',arguments:[pods,-n,nc-system]}]" \

+ --resource-group "<cluster_MRG>" \

+ --subscription "<subscription>"

+```

+```azcli

+az networkcloud baremetalmachine run-read-command --name "<bareMetalMachineName>" \

+ --limit-time-seconds 60 \

+ --commands "[{command:'kubectl describe',arguments:[pod,<podName>,-n,nc-system]}]" \

+ --resource-group "<cluster_MRG>" \

+ --subscription "<subscription>"

+```

+## Known services susceptible to OOM issues

+* cdi-operator

+* vulnerability-operator

+* cluster-metadata-operator

+## Service limits

+- You can override a field with **up to 50 values** in a single query. When your query exceeds 50 customized values, **all** customized values are dropped, and in all query results the field reverts to its default value. Tune your query to yield no more than 50 values to ensure no customized values are dropped.

+- The size limit for the `AlertName` field, and any other non-collection properties, is **256 bytes**.

+- The size limit for the `Description` field, and any other collection properties, is **5 KB**.

+- Values exceeding the size limits are dropped.

+| `noresvport` | n/a | Recommended for kernels below 5.18. Tells the NFS client to use a non-privileged source port when communicating with an NFS server for the mount point. Using the `noresvport` mount option helps ensure that your NFS share has uninterrupted availability after a reconnection. Using this option is strongly recommended for achieving high availability. |

+Use the following additional mount option with all access control models to enable Kerberos security: `sec=krb5`. Username and password must be omitted when sec=krb5 is in use.

+# [Identity Validation - Organization](#tab/orgvalidation)

+# [Identity Validation - Individual Developer](#tab/indiedevvalidation)

+To create an Individual identity validation request for an Individual Developer:

+1. In the Azure portal, go to your new Trusted Signing account.

+2. Confirm that you're assigned the Trusted Signing Identity Verifier role.

+ To learn how to manage, access by using role-based access control (RBAC), see [Tutorial: Assign roles in Trusted Signing](tutorial-assign-roles.md).

+3. On the Trusted Signing account **Overview** pane or on the resource menu under **Objects**, select **Identity validations**.

+4. Select **Organization**, in the dropdown select **Individual** and then select **Public**.

+ - Public identity validation applies to these certificate profile types: Public Trust, Public Trust Test, VBS Enclave.

+ - Private identity validation is only for Organizations.

+5. On **New identity validation**, provide the following information:

+ | Fields | Details |

+ | :- | :- |

+ | **First Name** | Use the exact name as it appears on your government-issued identification document for the Identity Validation process. |

+ | **Last Name** | Use the exact name as it appears on your government-issued identification document for the Identity Validation process. |

+ | **Primary Email** | Enter the email address that is going to receive the Identity Validation link. Make sure to this same email address when logging into the Microsoft Account to access the Identity Validation link. |

+ | **Street, City, Country, State, Postal code** | Enter the address as it appears on your government issued identification document or utility bill or bank statement. The city, state, and country from the address entered here's displayed on the certificate. |

+6. Select **Certificate subject preview** to see the preview of the information that appears in the certificate.

+- Your email address and street address aren't included in the certificate by default.

+7. Select **I accept Microsoft terms of use for trusted signing services**. You can download the Terms of Use to review or save them.

+8. Select the **Create** button.

+9. When the request is successfully created, the identity validation request status changes to **In Progress**.

+10. When the status changes to **Action Required**. Click on your name, a blade opens on the right-hand side. Click on the link under ΓÇ£Please complete your verification hereΓÇ¥.

+11. Follow the link to complete the Identity Validation process. Use the email address provided at the time of request creation to create a Microsoft account. Enter the credentials when prompted, and you'll be navigated to the next screen.

+12. Click on **Start** under our Trusted Partner > Au10tix to begin the validation process. You will be navigated to a 3rd party website.

+13. You need to switch to your mobile device to complete the process and present the relevant documentation when prompted.

+14. On your mobile device, open the Authenticator app, select Verified IDs, on bottom right youΓÇÖll see the QR code in blue. Click on that.

+15. In Azure portal, click on the link that you used to perform identity validation, scan the QR code under Present Verified ID from your mobile device, this completes the process.

+For successful completion it says: **Verification Successful**

+16. It takes a couple of minutes for the Identity Validation status on Azure portal to update. For a successful Verified ID the status on Azure portal changes to **Completed**.

+### Important information for public identity validation for individuals

+1. Minimum Requirements for Mobile OSes and supported Browsers:

+2. Types of ID Accepted:

+- Government-issued IDs such as passports, driving licenses, or ID cards.

+- Photo IDs (or a US Social Security Card).

+- Official government-issued IDs such as a passport, driverΓÇÖs license, or state ID.

+- Do not submit privately issued IDs such as library cards, school IDs, club membership cards, etc.

+3. Visibility/Low Light/Bright Light:

+- Do not use flash.

+- Do not place the ID in direct sunlight.

+- Hold the camera or mobile device steady while taking the picture.

+4. Best Practices for Supplemental Docs:

+- Utility Bills: Electricity, water, gas, or telephone bills (should be recent, typically within the last three months).

+- Bank Statements: Official statements from banks or credit card companies that show the individualΓÇÖs address.

+- The POA document must have the address, name, and date appear on the main page (first page), so multiple pages are not required.

+5. General best practices:

+- Single picture per file, if two-sided, create one file per side.

+- Handwritten documents are not accepted.

+- Do not crop the image (cut corners, miss parts) try to have margins on all sides of the captured image prior to capturing.

+- Do not use Photoshop or other editing software; do not alter the document in any way.

+- Do not use flash.

+- Take the photo from directly above the document while it is on a flat surface.

+- Avoid colored and noisy background.

+- Do not obstruct the ID (no fingers covering part of the document).

+- Use color images not lower than 200 DPI. The ideal image size is 500Kb. AU10TIX best practice is to accept images with 400 DPI and above.

+- The minimum threshold for the image size for an OK result is 600 W X 370 H pixels.

+- Accepted file types: .bmp .jpg .gif .tif .pdf.

+- Users cannot upload images smaller than 30kb or larger than 5MB.