Use TLS to secure a web service through Azure Machine Learning

APPLIES TO: Python SDK azureml v1

This article shows you how to secure a web service that's deployed through Azure Machine Learning.

You use HTTPS to restrict access to web services and secure the data that clients submit. HTTPS helps secure communications between a client and a web service by encrypting communications between the two. Encryption uses Transport Layer Security (TLS). TLS is sometimes still referred to as Secure Sockets Layer (SSL), which was the predecessor of TLS.

Tip

The Azure Machine Learning SDK uses the term "SSL" for properties that are related to secure communications. This doesn't mean that your web service doesn't use TLS. SSL is just a more commonly recognized term.

Specifically, web services deployed through Azure Machine Learning support TLS version 1.2 for AKS and ACI. For ACI deployments, if you are on older TLS version, we recommend re-deploying to get the latest TLS version.

TLS version 1.3 for Azure Machine Learning - AKS Inference is unsupported.

TLS and SSL both rely on digital certificates, which help with encryption and identity verification. For more information on how digital certificates work, see the Wikipedia topic Public key infrastructure.

Warning

If you don't use HTTPS for your web service, data that's sent to and from the service might be visible to others on the internet.

HTTPS also enables the client to verify the authenticity of the server that it's connecting to. This feature protects clients against man-in-the-middle attacks.

This is the general process to secure a web service:

1. Get a domain name.

2. Get a digital certificate.

3. Deploy or update the web service with TLS enabled.

4. Update your DNS to point to the web service.

Important

If you're deploying to Azure Kubernetes Service (AKS), you can purchase your own certificate or use a certificate that's provided by Microsoft. If you use a certificate from Microsoft, you don't need to get a domain name or TLS/SSL certificate. For more information, see the Enable TLS and deploy section of this article.

There are slight differences when you secure across deployment targets.

Important

Some of the Azure CLI commands in this article use the azure-cli-ml, or v1, extension for Azure Machine Learning. Support for the v1 extension will end on September 30, 2025. You will be able to install and use the v1 extension until that date.

We recommend that you transition to the ml, or v2, extension before September 30, 2025. For more information on the v2 extension, see Azure ML CLI extension and Python SDK v2.

Get a domain name

If you don't already own a domain name, purchase one from a domain name registrar. The process and price differ among registrars. The registrar provides tools to manage the domain name. You use these tools to map a fully qualified domain name (FQDN) (such as www.contoso.com) to the IP address that hosts your web service.

Get a TLS/SSL certificate

There are many ways to get an TLS/SSL certificate (digital certificate). The most common is to purchase one from a certificate authority (CA). Regardless of where you get the certificate, you need the following files:

• A certificate. The certificate must contain the full certificate chain, and it must be "PEM-encoded."
• A key. The key must also be PEM-encoded.

When you request a certificate, you must provide the FQDN of the address that you plan to use for the web service (for example, www.contoso.com). The address that's stamped into the certificate and the address that the clients use are compared to verify the identity of the web service. If those addresses don't match, the client gets an error message.

Tip

If the certificate authority can't provide the certificate and key as PEM-encoded files, you can use a utility such as OpenSSL to change the format.

Warning

Use self-signed certificates only for development. Don't use them in production environments. Self-signed certificates can cause problems in your client applications. For more information, see the documentation for the network libraries that your client application uses.

Enable TLS and deploy

For AKS deployment, you can enable TLS termination when you create or attach an AKS cluster in Azure Machine Learning workspace. At AKS model deployment time, you can disable TLS termination with deployment configuration object, otherwise all AKS model deployment by default will have TLS termination enabled at AKS cluster create or attach time.

For ACI deployment, you can enable TLS termination at model deployment time with deployment configuration object.

Deploy on Azure Kubernetes Service

Note

The information in this section also applies when you deploy a secure web service for the designer. If you aren't familiar with using the Python SDK, see What is the Azure Machine Learning SDK for Python?.

When you create or attach an AKS cluster in Azure Machine Learning workspace, you can enable TLS termination with AksCompute.provisioning_configuration() and AksCompute.attach_configuration() configuration objects. Both methods return a configuration object that has an enable_ssl method, and you can use enable_ssl method to enable TLS.

You can enable TLS either with Microsoft certificate or a custom certificate purchased from CA.

• When you use a certificate from Microsoft, you must use the leaf_domain_label parameter. This parameter generates the DNS name for the service. For example, a value of "contoso" creates a domain name of "contoso<six-random-characters>.<azureregion>.cloudapp.azure.com", where <azureregion> is the region that contains the service. Optionally, you can use the overwrite_existing_domain parameter to overwrite the existing leaf_domain_label. The following example demonstrates how to create a configuration that enables an TLS with Microsoft certificate:

  from azureml.core.compute import AksCompute
  
  # Config used to create a new AKS cluster and enable TLS
  provisioning_config = AksCompute.provisioning_configuration()
  
  # Leaf domain label generates a name using the formula
  #  "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
  #  where "######" is a random series of characters
  provisioning_config.enable_ssl(leaf_domain_label = "contoso")
  
  
  # Config used to attach an existing AKS cluster to your workspace and enable TLS
  attach_config = AksCompute.attach_configuration(resource_group = resource_group,
                                        cluster_name = cluster_name)
  
  # Leaf domain label generates a name using the formula
  #  "<leaf-domain-label>######.<azure-region>.cloudapp.azure.com"
  #  where "######" is a random series of characters
  attach_config.enable_ssl(leaf_domain_label = "contoso")
  

  Important

  When you use a certificate from Microsoft, you don't need to purchase your own certificate or domain name.

• When you use a custom certificate that you purchased, you use the ssl_cert_pem_file, ssl_key_pem_file, and ssl_cname parameters. The PEM file with pass phrase protection is not supported. The following example demonstrates how to use .pem files to create a configuration that uses a TLS/SSL certificate that you purchased:

  from azureml.core.compute import AksCompute
  
  # Config used to create a new AKS cluster and enable TLS
  provisioning_config = AksCompute.provisioning_configuration()
  provisioning_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                      ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")
  
  # Config used to attach an existing AKS cluster to your workspace and enable SSL
  attach_config = AksCompute.attach_configuration(resource_group = resource_group,
                                       cluster_name = cluster_name)
  attach_config.enable_ssl(ssl_cert_pem_file="cert.pem",
                                      ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")
  

For more information about enable_ssl, see AksProvisioningConfiguration.enable_ssl() and AksAttachConfiguration.enable_ssl().

Deploy on Azure Container Instances

When you deploy to Azure Container Instances, you provide values for TLS-related parameters, as the following code snippet shows:

from azureml.core.webservice import AciWebservice

aci_config = AciWebservice.deploy_configuration(
    ssl_enabled=True, ssl_cert_pem_file="cert.pem", ssl_key_pem_file="key.pem", ssl_cname="www.contoso.com")

For more information, see AciWebservice.deploy_configuration().

Update your DNS

For either AKS deployment with custom certificate or ACI deployment, you must update your DNS record to point to the IP address of scoring endpoint.

Important

When you use a certificate from Microsoft for AKS deployment, you don't need to manually update the DNS value for the cluster. The value should be set automatically.

You can follow following steps to update DNS record for your custom domain name:

1. Get scoring endpoint IP address from scoring endpoint URI, which is usually in the format of http://104.214.29.152:80/api/v1/service/<service-name>/score. In this example, the IP address is 104.214.29.152.

2. Use the tools from your domain name registrar to update the DNS record for your domain name. The record maps the FQDN (for example, www.contoso.com) to the IP address. The record must point to the IP address of scoring endpoint.

   Tip

   Microsoft does is not responsible for updating the DNS for your custom DNS name or certificate. You must update it with your domain name registrar.

3. After DNS record update, you can validate DNS resolution using nslookup custom-domain-name command. If DNS record is correctly updated, the custom domain name will point to the IP address of scoring endpoint.

   There can be a delay of minutes or hours before clients can resolve the domain name, depending on the registrar and the "time to live" (TTL) that's configured for the domain name.

For more information on DNS resolution with Azure Machine Learning, see How to use your workspace with a custom DNS server.

Update the TLS/SSL certificate

TLS/SSL certificates expire and must be renewed. Typically this happens every year. Use the information in the following sections to update and renew your certificate for models deployed to Azure Kubernetes Service:

Update a Microsoft generated certificate

If the certificate was originally generated by Microsoft (when using the leaf_domain_label to create the service), it will automatically renew when needed. If you want to manually renew it, use one of the following examples to update the certificate:

Important

• If the existing certificate is still valid, use renew=True (SDK) or --ssl-renew (CLI) to force the configuration to renew it. This operation will take about 5 hours to take effect.
• When the service was originally deployed, the leaf_domain_label is used to create a DNS name using the pattern <leaf-domain-label>######.<azure-region>.cloudapp.azure.com. To preserve the existing name (including the 6 digits originally generated), use the original leaf_domain_label value. Do not include the 6 digits that were generated.

Use the SDK

from azureml.core.compute import AksCompute
from azureml.core.compute.aks import AksUpdateConfiguration
from azureml.core.compute.aks import SslConfiguration

# Get the existing cluster
aks_target = AksCompute(ws, clustername)

# Update the existing certificate by referencing the leaf domain label
ssl_configuration = SslConfiguration(leaf_domain_label="myaks", overwrite_existing_domain=True, renew=True)
update_config = AksUpdateConfiguration(ssl_configuration)
aks_target.update(update_config)

Use the CLI

APPLIES TO: Azure CLI ml extension v1

az ml computetarget update aks -g "myresourcegroup" -w "myresourceworkspace" -n "myaks" --ssl-leaf-domain-label "myaks" --ssl-overwrite-domain True --ssl-renew

For more information, see the following reference docs:

• SslConfiguration
• AksUpdateConfiguration

Update custom certificate

If the certificate was originally generated by a certificate authority, use the following steps:

1. Use the documentation provided by the certificate authority to renew the certificate. This process creates new certificate files.

2. Use either the SDK or CLI to update the service with the new certificate:

   Use the SDK

   from azureml.core.compute import AksCompute
   from azureml.core.compute.aks import AksUpdateConfiguration
   from azureml.core.compute.aks import SslConfiguration
   
   # Read the certificate file
   def get_content(file_name):
       with open(file_name, 'r') as f:
           return f.read()
   
   # Get the existing cluster
   aks_target = AksCompute(ws, clustername)
   
   # Update cluster with custom certificate
   ssl_configuration = SslConfiguration(cname="myaks", cert=get_content('cert.pem'), key=get_content('key.pem'))
   update_config = AksUpdateConfiguration(ssl_configuration)
   aks_target.update(update_config)
   

   Use the CLI

   APPLIES TO: Azure CLI ml extension v1

   az ml computetarget update aks -g "myresourcegroup" -w "myresourceworkspace" -n "myaks" --ssl-cname "myaks"--ssl-cert-file "cert.pem" --ssl-key-file "key.pem"
   

For more information, see the following reference docs:

• SslConfiguration
• AksUpdateConfiguration

Disable TLS

To disable TLS for a model deployed to Azure Kubernetes Service, create an SslConfiguration with status="Disabled", then perform an update:

from azureml.core.compute import AksCompute
from azureml.core.compute.aks import AksUpdateConfiguration
from azureml.core.compute.aks import SslConfiguration

# Get the existing cluster
aks_target = AksCompute(ws, clustername)

# Disable TLS
ssl_configuration = SslConfiguration(status="Disabled")
update_config = AksUpdateConfiguration(ssl_configuration)
aks_target.update(update_config)

Next steps

Learn how to:

• Consume a machine learning model deployed as a web service
• Virtual network isolation and privacy overview
• How to use your workspace with a custom DNS server