Configuring SNI between Edge Message Processor and the backend server

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

Server Name Indication (SNI) allows multiple HTTPS backend servers to be served off the same IP address and port without requiring those backend servers to use the same TLS certificate. It is an extension of the TLS protocol. When SNI is enabled on a client, the client passes the hostname of the backend server as part of the initial TLS handshake. This allows the TLS server to determine which TLS certificate should be used to validate the request from the client.

By default, SNI is disabled on the Message Processor component in Edge for the Private Cloud to ensure backward compatibility with the existing backend servers. If your backend server is configured to support SNI, then you need to enable the SNI on the Message Processor component. Otherwise, the API requests going through Apigee Edge will fail with TLS Handshake Failures.

This document explains how to do the following:

Before you begin

Identification of SNI enabled server

This section describes how to identify whether or not a backend server is SNI enabled.

  1. Execute the openssl command and try to connect to the relevant server hostname (Edge Router or backend server) without passing the server name, as shown below:
    openssl s_client -connect hostname:port
    
  2. You may get the certificates and sometimes you may observe the handshake failure in the openssl command, as shown below:
    CONNECTED(00000003) 9362:error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.6/src/ssl/s23_clnt.c:593
    
  3. Execute the openssl command and try to connect to the relevant server hostname (Edge router or backend server) by passing the server name as shown below:
    openssl s_client -connect hostname:port -servername hostname
    
  4. If you get a handshake failure in step 1 or get different certificates in step 1 and step 2, then it indicates that the specified Server is SNI enabled.
  5. If you want to verify this for more than one backend server, then you need to repeat the above steps for each backend server.

If you find that you have one or more backend servers that are SNI enabled, then you need to enable SNI on the Message Processor component as explained below. Otherwise, the API requests going through Apigee Edge will fail with TLS Handshake Failures.

Enable SNI between Edge Message Processors and backend server

This section explains how to enable SNI between the Edge Message Processor and the backend server. SNI can be enabled through the property jsse.enableSNIExtension on the Message Processor component. To configure any property on the Message Processor, use the token according to the syntax described in How to configure Edge.

To enable SNI on the Message Processors, perform the following steps:

  1. Locate token for jsse.enableSNIExtension property
  2. Enable SNI on the Message Processor

Locate token for jsse.enableSNIExtension property

The following steps describe how to locate the token for the jsse.enableSNIExtension property:

  1. Search for the jsse.enableSNIExtension property in the Message Processor source directory /opt/apigee/edge-message-processor/source using the following command:
    grep -ri "jsse.enableSNIExtension" /opt/apigee/edge-message-processor/source
    
  2. The output of this command shows the token for Message Processor’s property jsse.enableSNIExtension as follows:
    /opt/apigee/edge-message-processor/source/conf/system.properties:jsse.enableSNIExtension={T}conf_system_jsse.enableSNIExtension{/T}
    

    Where the string between the {T}{/T} tags is the name of the token that you can set in the Message Processor's .properties file.

    Thus, the token for the property jsse.enableSNIExtension is as follows:

    conf_system_jsse.enableSNIExtension
    

Enable SNI on the Message Processor

The following steps describe how to enable SNI on the Apigee Message Processor component.

  1. On the Message Processor machine, open the following file in an editor. If it does not already exist, then create it.
    /opt/apigee/customer/application/message-processor.properties
    

    For example, to open the file using vi, enter the following command:

    vi /opt/apigee/customer/application/message-processor.properties
    
  2. Add a line in the following format to the properties file:
    conf_system_jsse.enableSNIExtension=true
    
  3. Save your changes.
  4. Ensure this properties file is owned by the apigee user as shown below:
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
    
  5. Restart the Message Processor as shown below:
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    
  6. Verify the SNI configuration is updated on the Message Processor.
  7. If you have more than one Message Processor, repeat these above steps on all the Message Processors.

Disable SNI between Edge Message Processors and backend server

Generally you should not see any issues after enabling SNI. However, if you observe any connectivity issues between Edge Message Processor and the backend server after enabling SNI, you can always disable the SNI by performing the following steps.

SNI can be disabled by setting the property jsse.enableSNIExtension back to false on the Message Processor component.

Disable SNI on the Message Processors

The following steps describe how to disable SNI on the Apigee Message Processors.

  1. On the Message Processor machine, open the following file in an editor. If it does not already exist, then create it.
    /opt/apigee/customer/application/message-processor.properties
    

    For example, to open the file using vi, enter the following command:

    vi /opt/apigee/customer/application/message-processor.properties
    
  2. If the line conf_system_jsse.enableSNIExtension=true exists in /opt/apigee/customer/application/message-processor.properties, then modify it as follows:
    conf_system_jsse.enableSNIExtension=false
    
  3. Save your changes.
  4. Ensure this properties file is owned by the apigee user as shown below:
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
    
  5. Restart the Message Processor as shown below:
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    
  6. Verify the SNI configuration is updated on the Message Processor.
  7. If you have more than one Message Processor, repeat the above steps on all the Message Processors.

Verifying SNI Configuration on the Message Processors

This section explains how to verify that the SNI configuration has been successfully updated on the Message Processors.

Even though you use the token conf_system_jsse.enableSNIExtension to configure SNI on the Message Processor, you need to verify that the actual property jsse.enableSNIExtension has been set with the new value.

  1. On the Message Processor machine, search for the property jsse.enableSNIExtension in the /opt/apigee/edge-message-processor/conf directory and check to see if it has been set with the new value as shown below:
    grep -ri "jsse.enableSNIExtension" /opt/apigee/edge-message-processor/conf
    
  2. If the SNI configuration is updated successfully on the Message Processor, then the command above shows the new value in the system.properties file.

    The sample result from the above command after you have enabled SNI on the Message Processor is as follows:

    /opt/apigee/edge-message-processor/conf/system.properties:jsse.enableSNIExtension=true
    

    Similarly, the sample result from the above command after you have disabled SNI on the Message Processor is as follows:

    /opt/apigee/edge-message-processor/conf/system.properties:jsse.enableSNIExtension=false
    

    In the above example output, note that the property jsse.enableSNIExtension has been updated to the new value true or false in system.properties. This indicates that SNI is successfully enabled or disabled on the Message Processor.

  3. If you still see the old value for the property jsse.enableSNIExtension, then verify that you have followed all the steps outlined in the appropriate section to enable or disable SNI correctly. If you have missed any step, repeat all the steps again correctly.
  4. If you are still not able to enable/disable SNI , then contact Apigee Edge Support.