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.

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.

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.

There are slight differences when you secure s across deployment targets.

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.

Enable TLS and deploy

For AKS deployment, you can enable TLS termination when you create or attach an AKS cluster in AzureML 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

When you create or attach an AKS cluster in AzureML 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.chinacloudapi.cn", 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.chinacloudapi.cn"
  # 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.chinacloudapi.cn"
  # 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 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.

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:

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