Edit

Share via

Manage protocols and ciphers in Azure API Management

APPLIES TO: All API Management tiers

Azure API Management supports multiple versions of Transport Layer Security (TLS) protocol to secure API traffic for:

  • 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.

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.

Screenshot of managing protocols and ciphers in the Azure portal.

Note

  • If you're using the self-hosted gateway, see self-hosted gateway security to manage TLS protocols and cipher suites.
  • The following tiers don't support changes to the default cipher configuration: Consumption, Basic v2, Standard v2, Premium v2.
  • In workspaces, 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

Go to your API Management instance

  1. In the Azure portal, search for and select API Management services:

    Screenshot that shows API Management services in the search results.

  2. On the API Management services page, select your API Management instance:

    Screenshot that shows an API Management instance on the API Management services page.

How to manage TLS protocols and cipher suites

  1. In the left navigation of your API Management instance, under Security, select Protocols + ciphers.
  2. Enable or disable desired protocols or ciphers.
  3. Select Save.

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.

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 of API Management and workspace gateways 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.
  2. Review the list of Recent client certificate renegotiations. The list shows API operations where clients recently used client certificate renegotiation.
  3. If you choose to enable TLS 1.3 for client-side connections, select Enable.
  4. 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.
  2. Select Disable.
  3. 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.
  2. Select Save.

Related content