Using SNI with Edge

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Server Name Indication (SNI) allows multiple HTTPS targets to be served off the same IP address and port without requiring those targets to use the same TLS certificate. When SNI is enabled on a client, the client passes the hostname of the target endpoint as part of the initial TLS handshake. That allows the TLS server to determine which TLS cert should be used to validate the request.

For example, if the request target is https://example.com/request/path, then the TLS client adds the server_name extension to the TLS handshake request, as shown below:

Edge supports SNI for:

  • Requests from a client app to an API proxy. In this scenario, Edge acts as the TLS server
  • Requests from Edge to the backend. In this scenario, Edge acts as the TLS client.

For additional information on SNI, see:

Supporting SNI for a request to API proxy on Edge

SNI support for requests to API proxies is controlled by hosts aliases and virtual hosts.

About virtual hosts and host aliases

With Edge, a virtual host defines the IP address and port, or DNS name and port, on which an API proxy is exposed and, by extension, the URL that apps use to access an API proxy. The IP address/DNS name corresponds to an Edge Router, and the port number is an open port on the Router.

When you create the virtual host, you also specify the host alias of the virtual host. Typically this is the DNS name of the virtual host. As part of determining the API proxy that handles the request, the Router compares the Host header of the incoming request to the list of available host aliases defined by all virtual hosts.

The combination of host alias and port number for the virtual host must be unique for all virtual hosts in the Edge installation. That means multiple virtual hosts can use the same port number if they have different host aliases.

A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol using TLS. When configuring a virtual host to use HTTPS, associate the virtual host with a keystore that contains the cert and private key used by the virtual host during TLS handshaking.

For additional information on virtual hosts, see:

How SNI works with host aliases

SNI allows you to have multiple virtual hosts defined on the same port, each with different TLS certs and keys. Edge then determines the virtual host, and the cert/key pair used by TLS, based on the server_name extension in the TLS handshake request.

The Edge Router reads the server_name extension in the TLS handshake request, and then uses it to search against the host aliases from all virtual hosts. If the Router detects a match with a host alias, the Router uses the TLS cert and key from the virtual host associated with the host alias. If no match is found, TLS handshaking fails.

Rather than having the TLS handshake fail, you can define a default cert/key pair, as described in the next sections.

Defining a default cert/key pair in Edge for the Cloud

Apigee provides a TLS certificate and private key to support HTTPS. While many customers prefer to use their own certificate and private key at deployment time, you can deploy your APIs using the Apigee cert and key.

In Edge for the Cloud, if the Router cannot match the SNI header to a host alias or if the client does not support SNI, then the Router uses the default certificate provided by Apigee, which is *.apigee.net.

Defining a default cert/key pair in Edge for the Private Cloud

In Edge for the Private Cloud, if no match is found between the server_name extension and the host aliases from all virtual hosts, or if the requesting client does not support SNI, you can configure the Router to use the cert/key from a default virtual host on the port. The default virtual host is defined by a combination of organization name, environment name, and virtual host name, in the form:

orgName_envName_vhName

The Router uses the cert/key from the combination of orgName_envName_vhName that comes first in alphabetical order. For example, the request comes in on port 443, and there are two virtual hosts defined for the org example in the environment prod:

  • virtual host name = default
  • virtual host name = test

In this example, the Router uses the cert/key from the virtual host named default because example_prod_default comes alphabetically before example_prod_test.

To enable the default virtual host:

  1. On the first Router node, edit /opt/apigee/customer/application/router.properties. If that file does not exist, create it.
  2. Add the following property to the file to enable you to define a default virtual host: 
    conf_load_balancing_load.balancing.driver.nginx.fallback.conf.enabled=true
  3. Restart the Router: 
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  4. Repeat these steps on all remaining Routers.

Rather than use the cert/key from the default virtual host, you can explicitly define the default cert/key on the Router. Use the following procedure to define an explicit default cert/key pair:

  1. On the first Router node, copy the cert and private key to a location on the Router node that is accessible by the apigee user. For example, /opt/apigee/customer/application.
  2. Change ownership of the files to the 'apigee. user: 
    chown apigee:apigee /opt/apigee/customer/application/myCert.pem
    chown apigee:apigee /opt/apigee/customer/application/myKey.pem
  3. Edit /opt/apigee/customer/application/router.properties. If that file does not exist, create it.
  4. Add the following properties to the file to enable you to specify the default cert/key:
    conf_load_balancing_load.balancing.driver.nginx.fallback.server.default.ssl.template.enabled=true
    conf_load_balancing_load.balancing.driver.nginx.fallback.conf.enabled=true
  5. Set the followng properties in router.properties to specify the location of the certy and key: 
    conf_load_balancing_load.balancing.driver.nginx.ssl.cert=/opt/apigee/customer/application/myCert.pem
conf_load_balancing_load.balancing.driver.nginx.ssl.key=/opt/apigee/customer/application/myKey.pem
  6. Restart the Router: 
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  7. Repeat these steps on all remaining Routers.

Supporting SNI for requests from Edge to the backend

Edge supports the use of SNI from Message Processors to target endpoints in Apigee Edge for Cloud and for Private Cloud deployments. By default, SNI is enabled on Edge Message Processors for the Cloud and disabled in the Private Cloud.

Using SNI to the backend in Edge for the Private Cloud

For Edge for the Private Cloud, to be backward compatible with existing target backends, Apigee disabled SNI by default. If your target backend is configured to support SNI, you can enable this feature as described below for your version of Edge.

No other Edge-specific configuration is required. If your target environment is configured for SNI, Edge supports it. Edge automatically extracts the hostname from the request URL and adds it to the TLS handshake request.

Enable SNI between Edge and the backend for Edge version 4.15.07.0x

Use the following procedure to enable SNI:

  1. On the first Message Processor node, open the file /opt/apigee4/conf/apigee/message-processor/system.properties in an editor.
  2. Set the following property to true in system.properties: 
    jsse.enableSNIExtension=true
  3. Restart the Message Processors: 
    /opt/apigee4/bin/apigee-service message-processor restart
  4. Repeat these steps on all remaining Message Processors.

Enable SNI between Edge and the backend for Edge version 4.16.01 and later

Use the following procedure to enable SNI:

  1. On the first Message Processor node, edit /opt/apigee/customer/application/message-processor.properties. If that file does not exist, create it.
  2. Add the following property to the file: 
    conf_system_jsse.enableSNIExtension=true
  3. Restart the Message Processor: 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
  4. Repeat these steps on all remaining Message Processors.