Configuring TLS for the New Edge experience

Edge for Private Cloud v4.19.01

By default, you access the New Edge experience over HTTP by using the IP address or DNS name of the New Edge experience node and port 3001. For example:

http://newue_IP:3001

Alternatively, you can configure TLS access to the New Edge experience so that you can access it in the form:

https://newue_IP:3001

TLS requirements

The New Edge experience only supports TLS v1.2. If you enable TLS on the New Edge experience, users must connect to the New Edge experience using a browser compatible with TLS v1.2.

TLS configuration properties

Execute the following command to configure TLS for the New Edge experience:

/opt/apigee/apigee-service/bin/apigee-service edge-management-ui configure-ssl -f configFile

Where configFile is the config file that you used to install the New Edge experience.

Before you execute this command, you must edit the config file to set the necessary properties that control TLS. The following table describes the properties that you use to configure TLS for the New Edge experience:

Property Description Required?
MANAGEMENT_UI_SCHEME

Sets the protocol, "http" or "https", used to access the New Edge experience. The default value is "http". Set it to "https" to enable TLS:

MANAGEMENT_UI_SCHEME=https
Yes
MANAGEMENT_UI_TLS_OFFLOAD

If "n", specifies that TLS requests to the New Edge experience are terminated at the New Edge experience. You must set MANAGEMENT_UI_TLS_KEY_FILE and MANAGEMENT_UI_TLS_CERT_FILE.

If "y", specifies that TLS requests to the New Edge experience are terminated on a load balancer, and that the load balancer then forwards the request to the New Edge experience by using HTTP.

If you terminate TLS on the load balancer, the New Edge experience still needs to be aware that the original request came in over TLS. For example, some cookies have a Secure flag set.

You must set MANAGEMENT_UI_SCHEME to "https" or else MANAGEMENT_UI_TLS_OFFLOAD is ignored:

MANAGEMENT_UI_SCHEME=https
MANAGEMENT_UI_TLS_OFFLOAD=y
Yes
MANAGEMENT_UI_TLS_KEY_FILE

MANAGEMENT_UI_TLS_CERT_FILE

If MANAGEMENT_UI_TLS_OFFLOAD=n, specifies the absolute path to the TLS key and cert files. The files must be formatted as PEM files with no passphrase, and must be owned by the "apigee" user.

The recommended location for these files is:

/opt/apigee/customer/application/edge-management-ui

If that directory does not exist, create it.

If MANAGEMENT_UI_TLS_OFFLOAD=y, then omit MANAGEMENT_UI_TLS_KEY_FILE and MANAGEMENT_UI_TLS_CERT_FILE. They are ignored because requests to the New Edge experience come in over HTTP.

Yes if MANAGEMENT_UI_TLS_OFFLOAD=n
MANAGEMENT_UI_PUBLIC_URIS

If MANAGEMENT_UI_TLS_OFFLOAD=n, specifies the URL of the New Edge experience.

Set this property based on other properties in the config file. For example:

MANAGEMENT_UI_PUBLIC_URIS=$MANAGEMENT_UI_SCHEME://$MANAGEMENT_UI_IP:$MANAGEMENT_UI_PORT

Where:

  • MANAGEMENT_UI_SCHEME specifies the protocol, "http" or "https", as described above.
  • MANAGEMENT_UI_IP specifies the IP address or DNS name of the New Edge experience.
  • MANAGEMENT_UI_PORT specifies the port used by the New Edge experience.

See Installing the New Edge Experience for more on these properties.

If MANAGEMENT_UI_TLS_OFFLOAD=y:

  • MANAGEMENT_UI_IP specifies the IP address or DNS name of the load balancer, not of the New Edge experience.
  • The load balancer and the New UE must use the same port number for requests, for example 3001. Use MANAGEMENT_UI_PORT to specify the port number on the load balancer and on the New UE.

Yes

SHOEHORN_SCHEME

Before you install the New Edge experience, you first install the base Edge UI, called shoehorn. The installation config file uses the following property to specify the protocol, "http", used to access the base Edge UI:

SHOEHORN_SCHEME=http

The base Edge UI does not support TLS, so even when you enable TLS on the New Edge experience, this property must still be set to "http".

Yes and set to "http"

Configure TLS

To configure TLS access to the New Edge experience:

  1. Generate the TLS cert and key as PEM files with no passphrase. For example:

    mykey.pem
    mycert.pem

    There are many ways to generate a TLS cert and key. For example, you can execute the following command to generate an unsigned cert and key:

    openssl req -x509 -newkey rsa:4096 -keyout mykey.pem -out mycert.pem -days 365 -nodes -subj '/CN=localhost'
  2. Copy the key and cert files to the /opt/apigee/customer/application/edge-management-ui directory. If that directory does not exist, create it.
  3. Make sure the cert and key are owned by the "apigee" user:

    chown apigee:apigee /opt/apigee/customer/application/edge-management-ui/*.pem
  4. Edit the config file that you used to install the New Edge experience to set the following TLS properties:

    # Set to https to enable TLS.
    MANAGEMENT_UI_SCHEME=https 
    # Do NOT terminate TLS on a load balancer.
    MANAGEMENT_UI_TLS_OFFLOAD=n
    
    # Specify the key and cert. 
    MANAGEMENT_UI_TLS_KEY_FILE=/opt/apigee/customer/application/edge-management-ui/mykey.pem
    MANAGEMENT_UI_TLS_CERT_FILE=/opt/apigee/customer/application/edge-management-ui/mycert.pem
    
    # Leave these properties set to the same values as when you installed the New Edge experience:
    MANAGEMENT_UI_PUBLIC_URIS=$MANAGEMENT_UI_SCHEME://$MANAGEMENT_UI_IP:$MANAGEMENT_UI_PORT
    SHOEHORN_SCHEME=http
  5. Execute the following command to configure TLS:

    /opt/apigee/apigee-service/bin/apigee-service edge-management-ui configure-ssl -f configFile

    Where configFile is the name of the config file.

    The script restarts the New Edge experience.

  6. Run the following commands to setup and restart shoehorn:

    /opt/apigee/apigee-service/bin/apigee-service edge-ui setup -f configFile
    /opt/apigee/apigee-service/bin/apigee-service edge-ui restart

    After the restart, the New Edge experience supports access over HTTPS. If you cannot log in to the New Edge experience after enabling TLS, clear the browser cache and try logging in again.

Configure the New Edge experience when TLS terminates on the load balancer

If you have a load balancer that forwards requests to the New Edge experience, you might choose to terminate the TLS connection on the load balancer, and then have the load balancer forward requests to the New Edge experience over HTTP:

Terminate TLS on load balancer

This configuration is supported but you need to configure the load balancer and the New Edge experience accordingly.

To configure the New Edge experience when TLS terminates on the load balancer:

  1. Edit the config file that you used to install the New Edge experience to set the following TLS properties:

    # Set to https to enable TLS
    MANAGEMENT_UI_SCHEME=https
    # Terminate TLS on a load balancer
    MANAGEMENT_UI_TLS_OFFLOAD=y
    # Set to the IP address or DNS name of the load balancer.
    MANAGEMENT_UI_IP=LB_IP_DNS
    # Set to the port number for the load balancer and New Edge experience.
    # The load balancer and the New Edge experience must use the same port number.
    MANAGEMENT_UI_IP=3001
    
    # Leave these properties set to the same values as when you installed the New Edge experience:
    MANAGEMENT_UI_PUBLIC_URIS=$MANAGEMENT_UI_SCHEME://$MANAGEMENT_UI_IP:$MANAGEMENT_UI_PORT
    SHOEHORN_SCHEME=http
    

    If you set MANAGEMENT_UI_TLS_OFFLOAD=y, omit MANAGEMENT_UI_TLS_KEY_FILE and MANAGEMENT_UI_TLS_CERT_FILE. They are ignored because requests to the New Edge experience come in over HTTP.

  2. Execute the following command to configure TLS:

    /opt/apigee/apigee-service/bin/apigee-service edge-management-ui configure-ssl -f configFile

    Where configFile is the name of the config file.

    The script restarts the New Edge experience.

  3. Run the following commands to setup and restart shoehorn:

    /opt/apigee/apigee-service/bin/apigee-service edge-ui setup -f configFile
    /opt/apigee/apigee-service/bin/apigee-service edge-ui restart

    After the restart, the New Edge experience supports access over HTTPS. If you cannot log in to the New Edge experience after enabling TLS, clear the browser cache and try logging in again.

Disable TLS on the New Edge experience

To disable TLS on the New Edge experience:

  1. Edit the config file that you used to install the New Edge experience to set the following TLS property:

    # Set to http to disable TLS.
    MANAGEMENT_UI_SCHEME=http
    
    # Only if you had terminated TLS on a load balancer,
    # reset to the IP address or DNS name of the New Edge experience.
    MANAGEMENT_UI_IP=newue_IP_DNS
    
  2. Execute the following command to disable TLS:

    /opt/apigee/apigee-service/bin/apigee-service edge-management-ui configure-ssl -f configFile

    Where configFile is the name of the config file.

    The script restarts the New Edge experience.

  3. Run the following commands to setup and restart shoehorn:

    /opt/apigee/apigee-service/bin/apigee-service edge-ui setup -f configFile
    /opt/apigee/apigee-service/bin/apigee-service edge-ui restart

    You can now access the New Edge experience over HTTP. If you cannot log in to the New Edge experience after disabling TLS, clear the browser cache and try logging in again.