Merge pull request #303754 from dlepow/tls13

[APIM] TLS 1.3 support - classic tiers

Author: denrea

articles/api-management/api-management-howto-manage-protocols-ciphers.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 08/02/2022
+ms.date: 08/12/2025
 ms.author: danlep
 ---
 
@@ -15,12 +15,13 @@ ms.author: danlep
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
 Azure API Management supports multiple versions of Transport Layer Security (TLS) protocol to secure API traffic for:
-* Client side
-* Backend side
+
+* Client side (client to API Management gateway)
+* Backend side (API Management gateway to backend)
 
 API Management also supports multiple cipher suites used by the API gateway.
 
-By default, API Management enables TLS 1.2 for client and backend connectivity and several supported cipher suites. This guide shows you how to manage protocols and ciphers configuration for an Azure API Management instance.
+Depending on the service tier, API Management supports TLS versions up to 1.2 or TLS 1.3 for client and backend connectivity and several supported cipher suites. This guide shows you how to manage protocols and ciphers configuration for an Azure API Management instance.
 
 :::image type="content" source="media/api-management-howto-manage-protocols-ciphers/api-management-protocols-ciphers.png" alt-text="Screenshot of managing protocols and ciphers in the Azure portal.":::
 
@@ -29,25 +30,72 @@ By default, API Management enables TLS 1.2 for client and backend connectivity a
 > * The following tiers don't support changes to the default cipher configuration: **Consumption**, **Basic v2**, **Standard v2**, **Premium v2**. 
 > * In [workspaces](workspaces-overview.md), the managed gateway doesn't support changes to the default protocol and cipher configuration.
 
+> [!NOTE]
+> Depending on the API Management service tier, changes can take 15 to 45 minutes or longer to apply. An instance in the Developer service tier has downtime during the process. Instances in the Basic and higher tiers don't have downtime during the process.  
+
+
 ## Prerequisites
 
 * An API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).
 
 [!INCLUDE [api-management-navigate-to-instance.md](../../includes/api-management-navigate-to-instance.md)]
 
-## How to manage TLS protocols cipher suites
+## How to manage TLS protocols and cipher suites
 
 1. In the left navigation of your API Management instance, under **Security**, select **Protocols + ciphers**.  
 1. Enable or disable desired protocols or ciphers.
 1. Select **Save**.
 
-Changes can take 1 hour or longer to apply. An instance in the Developer service tier has downtime during the process. Instances in the Basic and higher tiers don't have downtime during the process.  
-
 > [!NOTE]
 > Some protocols or cipher suites (such as backend-side TLS 1.2) can't be enabled or disabled from the Azure portal. Instead, you'll need to apply the REST API call. Use the `properties.customProperties` structure in the [Create/Update API Management Service](/rest/api/apimanagement/current-ga/api-management-service/create-or-update) REST API.
 
+## TLS 1.3 support in classic tiers
+
+TLS 1.3 support is available in the API Management classic service tiers (**Consumption**, **Developer**, **Basic**, **Standard**, and **Premium**). In most instances created in those service tiers, TLS 1.3 is permanently enabled by default for client-side connections. Enabling backend-side TLS 1.3 is optional. TLS 1.2 is also enabled by default on both client and backend sides.
+
+TLS 1.3 is a major revision of the TLS protocol that provides improved security and performance. It includes features such as reduced handshake latency and improved security against certain types of attacks.
+
+> [!NOTE]
+> The [v2 tiers](v2-service-tiers-overview.md) of API Management and [workspace gateways](workspaces-overview.md) support TLS 1.2 by default for client-side and backend-side connections. They don't currently support TLS 1.3.
+
+### Optionally enable TLS 1.3 when clients require certificate renegotiation
+
+TLS 1.3 doesn't support certificate renegotiation. Certificate renegotiation in TLS allows client and server to renegotiate connection parameters mid-session for authentication without terminating the connection.
+
+Services that we identified as reliant on client certificate renegotiation do not have TLS 1.3 enabled by default. 
+
+> [!WARNING]
+> If your APIs are accessed by TLS-compliant clients that rely on certificate renegotiation, enabling TLS 1.3 for client-side connections will cause those clients to fail to connect. Review APIs that recently used certificate renegotiation before enabling client-side TLS 1.3 in any service that doesn't have it enabled by default.
+
+To enable TLS 1.3 for client-side connections in these instances, configure settings on the **Protocols + ciphers** page:
+
+1. On the **Protocols + ciphers** page, in the **Client protocol** section, next to **TLS 1.3**, select **View and manage configuration**.
+1. Review the list of **Recent client certificate renegotiations**. The list shows API operations where clients recently used client certificate renegotiation.
+1. If you choose to enable TLS 1.3 for client-side connections, select **Enable**.
+1. Select **Close**.
+
+After enabling TLS 1.3, review gateway request metrics or TLS-related exceptions in logs that indicate TLS connection failures. If necessary, disable TLS 1.3 for client-side connections and downgrade to TLS 1.2.
+
+If you need to disable TLS 1.3 for client-side connections in these instances, configure settings on the **Protocols + ciphers** page:
+
+1. On the **Protocols + ciphers** page, in the **Client protocol** section, next to **TLS 1.3**, select **View and manage configuration**.
+1. Select **Disable**.
+1. Select **Close**.
+
+### Backend-side TLS 1.3
+
+Enabling backend-side TLS 1.3 is optional. If you enable it, API Management uses TLS 1.3 for connections to your backend services.
+
+> [!WARNING]
+> Enabling TLS 1.3 for backend-side connections will cause connection failures with backend services that rely on client certificate renegotiation between API Management and the backends.
+
+You can enable backend-side TLS 1.3 from the **Protocols + ciphers** page:    
+
+1. On the **Protocols + ciphers** page, in the **Backend protocol** section, enable the **TLS 1.3** setting.
+1. Select **Save**.
+
 ## Related content
 
 * For recommendations on securing your API Management instance, see [Azure security baseline for API Management](/security/benchmark/azure/baselines/api-management-security-baseline).
-* Learn about security considerations in the API Management [landing zone accelerator](/azure/cloud-adoption-framework/scenarios/app-platform/api-management/security).
+* Learn about security considerations in the API Management [Architecture best practices for API Management](/azure/well-architected/service-guides/azure-api-management#).
 * Learn more about [TLS](/dotnet/framework/network-programming/tls).