Edit

Share via

How to migrate to TLS (Transport Layer Security) 1.3 for Service Fabric

  • Article

This article explains how to enable TLS 1.3 on Service Fabric clusters. TLS helps manage the HTTP endpoints of your clusters.

If you only use certificates and don't need to define endpoints for your clusters, you only need to enable exclusive authentication mode. To enable this mode, you only need to complete the Upgrade to the latest Service Fabric runtime version and Enable exclusive authentication mode steps. Callouts are made when appropriate. If you later decide to enable token-based authentication, you need to complete the skipped steps.

Note

The steps in this article are for Windows machines. Linux isn't supported at this time.

Note

Support for TLS 1.3 was introduced with Service Fabric version 10.1CU2 (10.1.1951.9590). However, TLS 1.3 won't be enabled when using TLS 1.3 for Service Fabric Transport endpoints of user applications running in Windows 8 compatibility mode. In this scenario, Windows 10 compatibility mode must be declared in the Windows application manifests for TLS 1.3 to successfully enabled.

Prerequisites

  1. Determine the Service Fabric runtime version of your cluster. You can see your cluster's runtime version by logging in the Azure portal, viewing your cluster in the Service Fabric Explorer, or connecting to your cluster via PowerShell.
  2. Ensure all the nodes in your cluster are upgraded to Windows Server 2022.
  3. Determine if you use token-based authentication. You can check in the portal or review your cluster's manifest in the Service Fabric Explorer. If you do use token-based authentication, Microsoft Entra ID settings appear in the cluster manifest.
  4. Use the correct API version for deployments, depending on your cluster type:
    • For managed clusters, use 2023-12-01-preview or higher
    • For classic clusters, use 2023-11-01-preview or higher

Once you complete these prerequisite steps, you're ready to enable TLS 1.3 on your Service Fabric clusters.

Upgrade to the latest Service Fabric runtime version

In this step, you upgrade your cluster's runtime version to the latest version, which supports TLS 1.3.

Follow the steps in Upgrade the Service Fabric version that runs on your cluster. When you're finished, return to this article.

If you don't use token-based authentication for authenticating to your clusters, you should skip the next two steps. Instead, proceed to Enable exclusive authentication mode. If you use token-based authentication for authenticating to your clusters, proceed to the next step.

Define a new HTTP endpoint

Note

If you don't use token-based authentication for authenticating to your clusters, you should skip this step and the next. Instead, proceed to Enable exclusive authentication mode.

In this step, you define a new HTTP endpoint to use for token-based authentication to your cluster. You must define a new endpoint because TLS 1.3 doesn't easily support mixed mode authentication, where both X.509 certificates and OAuth 2.0 bearer tokens. Service Fabric cluster management endpoints typically use mixed mode authentication, so enabling TLS 1.3 without creating a new endpoint would break your cluster management endpoints.

Define a new endpoint exclusively dedicated to token-based authentication and do so for each node type in your cluster. In the following JSON snippet, we demonstrate how to define an endpoint in a cluster manifest with an example port number of 19079:

"nodeTypes": [
  {
    "name": "parameters('vmNodeType0Name')]",
    ...
    "httpGatewayTokenAuthEndpointPort": "19079",
    ...
  }
]

You can use any port number. It should be the same value throughout the cluster and should be selected from the range of ports reserved for the Service Fabric runtime.

To deploy the new endpoint, you have two options:

  • Upgrade the configuration of an existing cluster using the new manifest
  • Define the endpoint at deployment time of a new cluster

Cluster configuration upgrade for an existing

You can follow the steps in Customize cluster settings using Resource Manager templates section of the Upgrade the configuration of a cluster in Azure. When editing the JSON in step 4, make sure to update the properties element to include the new endpoint definition previously detailed in a sample JSON snippet.

Deploy a new cluster

You can follow the steps in the appropriate quickstart for the type of Service Fabric cluster you use. Make sure to edit the template to include the new endpoint definition previously detailed in the sample JSON snippet.

Migrate to the new token authentication endpoint

Note

If you don't use token-based authentication for authenticating to your clusters, you should skip this step and should've skipped the previous step. Instead, proceed to Enable exclusive authentication mode.

In this step, you need to find and update all clients that used token-based authentication to target the new token authentication endpoint. These clients made include scripts, code, or services. Any clients still addressing the old gateway port break when the port starts accepting TLS 1.3 connections. Also note that this port could be parameterized or have a different value than the Service Fabric-defined default.

Some examples of changes that need to be made:

  • Microsoft Entra ID applications
  • Any scripts that reference the existing endpoint
  • Load Balancer (LB) inbound Network Address Translation (NAT), Health Probe, and LB rules that reference the existing endpoint
  • Network Security Group (NSG) rules

You also need to migrate traffic that requires token-based authentication to the new endpoint.

Enable exclusive authentication mode

In this step, you enable exclusive authentication mode. As a safety mechanism, TLS 1.3 isn't offered on the default HTTP gateway endpoint until the cluster owner enables exclusive authentication mode.

enableHttpGatewayExclusiveAuthMode is a new setting with a default value of false. You to set this new setting to true. If you use token-based authentication, you can set enableHttpGatewayExclusiveAuthMode at the same time as the new endpoint definition in the previous steps. This setting update was only introduced sequentially to minimize the chance of breakages.

Warning

If users aren't fully migrated to the new set of endpoints, this is a breaking change.

Important

The Service Fabric runtime blocks enabling the exclusive authentication mode if token-based authentication is enabled on your cluster but a separate endpoint for token-based authentication isn't yet specified.

However, nothing in the cluster can detect breaks in external clients that attempt to authenticate using tokens against the newly exclusive default HTTP gateway port.

After you introduce this new setting to your cluster's configuration, you'll lose token-based access to the previous endpoint. You can access Service Fabric Explorer via the new port you defined if you completed the Define a new HTTP endpoint step.

To update the enableHttpGatewayExclusiveAuthMode setting, you have two options:

  • Upgrade the configuration of an existing cluster using the new manifest
  • Define the endpoint at deployment time of a new cluster

Cluster configuration upgrade for an existing

You can follow the steps in Customize cluster settings using Resource Manager templates section of the Upgrade the configuration of a cluster in Azure. When editing the JSON in step 4, make sure to update the properties element to include the new setting shown in the following JSON snippet.

  "enableHttpGatewayExclusiveAuthMode": true

Deploy a new cluster

You can follow the steps in the appropriate quickstart for the type of Service Fabric cluster you use. Make sure to edit the template to include the new endpoint definition previously detailed in the sample JSON snippet.

Next steps

There aren't any specific steps you need to complete after migrating your cluster to TLS 1.3. However, some useful related articles are including in the following links: