Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Configuring TLS access to an API for the Private Cloud

A virtual host on Edge defines the domains and ports on which an API proxy is exposed, and, by extension, the URL that apps use to access an API proxy.

A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol that uses TLS. When configuring a virtual host to use HTTPS and TLS, you create a virtual host on Edge and configure the virtual host to use a keystore and truststore.

This document describes how to create a virtual host for an on-premises deployment of Edge. To create a virtual host for a cloud deployment of Edge, see Using TLS in a cloud-based Edge installation.

参考資料 :

If your installation uses a load balancer, and the load balancer is responsible for handling encrypted traffic, then you still need to create the virtual host. However, your network configuration will determine whether or not the virtual host has to support TLS between the load balancer and the Router. See Using TLS in a Private Cloud installation for more. 

What you need to create a virtual host

Before you create a virtual host, you should have the following information:

  • The publicly facing domain name of the virtual host. For example, you should know if the publicly facing name is api.myCompany.com, myapi.myCompany.com, etc. That information is used when you create the virtual host and also when you create the DNS record for the virtual host.
  • For one-way TLS, you need to create a keystore where the keystore contains the following:
    • TLS certificate - either a certificate signed by a certificate authority (CA), or a chain of certificates where the last certificate is signed by a CA.
    • Private key - Edge supports key sizes up to 2048 bits. A passphrase is optional.
  • For two-way TLS, you need a keystore and you need a truststore to hold the client's certificate and, optionally, certificate's CA chain. You need the truststore even if the cert is signed by a CA.

See Keystores and Truststores for more information on creating keystores and truststores.

About host aliases

Edge for Private Cloud バージョン 4.16.01 からは、仮想ホストの作成時にホストエイリアスを指定する必要があります。4.16.01 以前のリリースでは、ホストエイリアスは省略可能でした。

 

Also, the combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation.

When you create the virtual host, you must specify the host alias of the virtual host. Typically this is the DNS name of the virtual host.

The Edge Router compares the Host header of the incoming request to the list of available host aliases as part of determining the API proxy that handles the request. When making a request through a virtual host, either specify a domain name that matches the host alias of a virtual host, or specify the IP address of the Router and the Host header containing the host alias.

For example, if you created a virtual host with a host alias of myapis.apigee.net on port 9001, then a cURL request to an API through that virtual host could use one of the following forms:

  • If you have a DNS entry for myapis.apigee.net:
    curl http://myapis.apigee.net:9001/{proxy-base-path}/{resource-path}
  • If you do not have a DNS entry for myapis.apigee.net:
    curl http://<routerIP>:9001/{proxy-base-path}/{resource-path} -H 'host: myapis.apigee.net'
    In this form, you specify the IP address of the Router, and pass the host alias in the Host header. 
    Note: The curl command, most browsers, and many other utilities automatically append the Host header with the domain as part of the request, so you can actually use a curl command in the form:
    curl http://<routerIP>:9001/{proxy-base-path}/{resource-path} 

Options when you do not have a DNS entry for the virtual host

One option when you do not have a DNS entry is to set the host alias to the IP address of the Router and port of the virtual host, as <routerIP>:port. For example:

192.168.1.31:9001

When you make a curl command in the form below:

curl http://<routerIP>:9001/{proxy-base-path}/{resource-path} 

This option is preferred because it works well with the Edge UI. 

If you have multiple Routers, add a host alias for each Router, specifying the IP address of each Router and port of the virtual host. 

Alternatively, you can set the host alias to a value, such as temp.hostalias.com. Then, you have to pass the Host header on every request:

curl -v http://<routerIP>:9001/{proxy-base-path}/{resource-path} -H 'Host: temp.hostalias.com'

Or, add the host alias to your /etc/hosts file. For example, add this line to /etc/hosts:

192.168.1.31   temp.hostalias.com

Then you can make a request as if you had a DNS entry:

curl -v http://myapis.apigee.net:9001/{proxy-base-path}/{resource-path} 

About virtual host ports on Edge for Private Cloud releases 4.16.01 and later

When creating a virtual host, you specify the Router port used by the virtual host. For example, port 9001.

For Apigee for Private Cloud releases 4.16.01 and later, by default, the Router runs as the user "apigee" which does not have access to privileged ports, typically ports 1024 and below. If you want to create a virtual host that binds the Router to a protected port then you have to configure the Router to run as a user with access to those ports.  See Setting up a virtual host for more.  

Virtual host configuration

To create a virtual host, create an XML object that defines the virtual host. For example, the following XML object defines a virtual host that uses the HTTP protocol:

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>DNS_name_or_IP:port</HostAlias> 
   </HostAliases> 
   <Interfaces/>
   <Port>9005</Port> 
</VirtualHost>

Edge for Private Cloud バージョン 4.16.01 からは、仮想ホストの作成時にホストエイリアスを指定する必要があります。4.16.01 以前のリリースでは、ホストエイリアスは省略可能でした。

Notice that the virtual host contains a name property. You use the value of the name property to configure an API proxy to use the virtual host.

You can then access an API proxy through this virtual host by making a request to:

http://<routerIP>:<port>/{proxy-base-path}/{resource-path}
https://<routerIP>:<port>/{proxy-base-path}/{resource-path}

プレースホルダ:

  • http or https: If the virtual host is configured to support TLS, use HTTPS. If the virtual host does not support TLS, use HTTP. 
  • <routerIP>:<port> is the IP address and port number of the virtual host.
  • {proxy-base-path} and {resource-path} are defined when you create the API proxy.

Typically, you do not publish your APIs to customers with an IP address and port number. Instead, you define a DNS entry for the Router and port. For example:

http://api.myCompany.com/{proxy-base-path}/{resource-path}
​https://api.myCompany.com/{proxy-base-path}/{resource-path}

If you define the DNS entry, then you must create a host alias for the virtual host that matches the domain name of the DNS entry. The host alias must match the string that the client passes in the Host header. From the example above, you would specify a host alias of api.myCompany.com

<VirtualHost name="myVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
</VirtualHost>

Configuring a virtual host for TLS

The next XML object uses the <SSLInfo> element to define a virtual host for a one-way TLS configuration over HTTPS:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Because Edge originally supported SSL, the tag that you use to configure TLS is named <SSLInfo>

In this example, the <Enabled> element is set to true to enable one-way TLS, and the <KeyStore> and <KeyAlias> elements specify the keystore and key used by the TLS connection. 

To enable two-way TLS, set the <ClientAuthEnabled> element to true, and specify a truststore using the <TrustStore> element. The truststore holds the client's certificate and, optionally, certificate's CA chain.

Deciding how to specify the keystore and truststore name in the virtual host

In the virtual host example above, you specified the keystore by using a reference. A reference is a variable that contains the name of the keystore, rather than specifying the keystore name directly.

The advantage to using a reference is that you can change the value of the reference to change the keystore used by the virtual host, usually because the cert in the current keystore is expiring in the near future. Changing the value of the reference does not require you to restart the Edge Router. 

You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore.

Alternatively, you can use a literal keystore name in the virtual host. However, if you ever modify the virtual host to change the keystore name, you have to restart the Edge Routers.

Restrictions in using references to keystores and truststore

You must take into account the following restriction when using references to keystores and truststores:

  • You can only use keystore and truststore references in virtual hosts if you support SNI and you terminate SSL on the Apigee Routers.
  • If you have a load balancer in front of the Apigee Routers, and you terminate TLS on the load balancer, then you cannot use keystore and truststore references in virtual hosts. 

Setting the TLS ciphers and protocols supported by the virtual host for Edge 4.15.07 and earlier

If you are using Edge version 4.15.07 and earlier, then you set the TLS protocol and ciphers used by the virtual host by using the <Ciphers> and <Protocols> child tags of the <SSLInfo> tag. These tags are described in the table below.

例:

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>myTestKeystore</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>    
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

The <Cipher> tag uses the Java and JSSE name of the cipher. For example, for Java 8 see http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites

Specifying the TLS ciphers and protocols supported by the virtual host for Edge 4.16.01 to 4.16.09

In Edge 4.16.01 through 4.16.09, you set the default ciphers and protocols for virtual hosts globally on the Router. These defaults then apply to all virtual hosts.

You cannot override these value for specific virtual hosts. All virtual hosts use the same values for protocol and cipher.

Use tokens to specify the default protocols and ciphers:

  • To specify the default protocols, use the token conf_load_balancing_load.balancing.driver.server.ssl.protocols
  • To specify the default ciphers for the Router, use the token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

The default value of the conf_load_balancing_load.balancing.driver.server.ssl.protocols token is:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

This setting specifies that the Router supports TLS versions 1.0, 1.1, and 1.2. Specify a space delimited list of values to the token.

The default value of the conf_load_balancing_load.balancing.driver.server.ssl.ciphers token is:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

This setting specifies:

  • Key length of 128 bits or more required (HIGH).
  • Exclude ciphers with no authentication (!aNULL)
  • Exclude cipher suites using MD5 (!MD5)
  • Exclude cipher suites using DH (including anonymous DH, ephemeral DH and fixed DH) AND triple DES (!DH+3DES)
  • Exclude cipher suites using RSA key exchange AND triple DES (!RSA+3DES)

For information on the syntax and values allowed by this token, see https://www.openssl.org/docs/man1.0.2/apps/ciphers.html. Note that this token uses the OpenSSL cipher names, such as AES128-SHA256, and not the Java/JSSE cipher names, such as TLS_RSA_WITH_AES_128_CBC_SHA256.

To set the token for the Router:

  1. Edit the /opt/apigee/customer/application/router.properties file. If that file does not exist, create it.
  2. Set the conf_load_balancing_load.balancing.driver.server.ssl.ciphers token. For example, to specify TLSv1.2 only and exclude cipher suites using pre-shared keys, add!PSK:
    conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
    conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK
  3. Ensure that the router.properties file is owned by apigee:
    ​> chown apigee:apigee ​/opt/apigee/customer/application/router.properties
  4. Restart the Edge Router:
    > /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  5. Check the value of the token:
    > /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Setting virtual host parameters for Edge version 4.17.01 and later

If you are using Edge version 4.17.01 and later, then you can set some TLS properties for an individual virtual host, such as TLS protocol and cipher, by using the <Properties> child tag of the <VirtualHost> tag. These tags are described in the table below.

You can still use tokens to set the default ciphers and protocols for virtual hosts globally on the Router, as described in the previous section for Edge 4.16.01 through 4.16.09. This section describes new properties added in 4.17.01 that let you override those defaults for an individual virtual host.

例:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

For information on the syntax and values allowed by the ssl_ciphers token, see https://www.openssl.org/docs/man1.0.2/apps/ciphers.html. Note that this token uses the OpenSSL cipher names, such as AES128-SHA256, and not the Java/JSSE cipher names, such as TLS_RSA_WITH_AES_128_CBC_SHA256.

Setting the base URL displayed by the Edge UI for an API proxy

The Edge UI displays the URL of an API proxy based on settings in the virtual host corresponding to where the proxy is deployed. This display can include the Router port number of the virtual host.

In most cases, the URL displayed in the Edge UI is the correct URL for making external requests to the proxy. However, for some configurations, the displayed URL is not correct. For example, any one of the following configurations can cause the displayed URL displayed to not correspond to the actual URL used to make external requests to the proxy:

  • SSL termination occurs at a load balancer 
  • Port mapping occurs between a load balancer and Apigee routers 
  • A load balancer configured with path rewriting

Edge for Private Cloud 4.17.05 and later support an attribute on the virtual host called <BaseUrl> that lets you override the URL displayed by the Edge UI. Here's an example showing the virtual host object with the new <BaseURL> attribute. In this example, the value "http://myCo.com" appears in the Edge UI:

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>DNS_name_or_IP:9005</HostAlias> 
   </HostAliases> 
   <BaseUrl>http://myCo.com</BaseUrl>     
   <Interfaces/>
   <Port>9005</Port> 
</VirtualHost>

If <BaseUrl> is not set, the default, then the default URL rendered by the Edge UI will appear as: "http://DNS_name_or_IP:9005/", whereas actual host alias setup is "http://myCo.com". 

You can also set the base URL when creating an organization by using the VHOST_BASEURL property with the apigee-provision utility. See Onboard an organization for more.

Virtual host configuration parameters

The following table lists the XML elements that you use to configure a virtual host:

Element

説明

デフォルト

Required

VirtualHost

Specifies the name of the virtual host. You use that name to reference the virtual host when configuring an API proxy.

The characters that you can use in the name attribute are restricted to: A-Z0-9._\-$ %.

なし

Port

Specifies the port number used by the virtual host. Ensure that the port is open on the Edge Router.

If you specify a port in a <HostAlias> element, then the port number specified by <Port> must match it.

While it is not required, it is a best practice to use a different port for each virtual host. 

Note for Apigee for Private Cloud releases 4.16.01 and later: When creating a virtual host, you specify the Router port used by the virtual host. For example, port 9001. By default, the Router runs as the user "apigee" which does not have access to privileged ports, typically ports 1024 and below. If you want to create a virtual host that binds the Router to a protected port then you have to configure the Router to run as a user with access to those ports.  See Setting up a virtual host for more.  

Note for Apigee for Private Cloud releases prior to 4.16.01: A Router can listen to only one HTTPS connection per virtual host, on a specific port, with the specified cert. Therefore, multiple virtual hosts cannot use the same port number if TLS termination occurs on the Router at the specified port.

なし

BaseUrl Overrides the URL displayed by the Edge UI for an API proxy deployed to the virtual host. Useful when you have an external load balancer in front of the Edge Routers. なし

HostAliases

 

HostAlias

The publicly visible DNS name of the virtual host on the Router, optionally including the port number. The combination of host alias name 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.

You must create a DNS record that matches the host alias, and the host alias must match the string that the client passes in the Host header.

The port number in the HostAlias is optional. If you specify the port as part of the host alias, you must also specify the same port by using the <Port> element. Or, you can specify two <HostAlias> elements, one with the port number and one without.

You can have multiple <HostAlias> definitions in the same <VirtualHost> definition, corresponding to multiple DNS entries for the virtual host, but not for multiple ports. If you want multiple ports, create multiple <VirtualHost> definitions with different ports.

If you are setting the host alias by using the IP addresses of your Routers, and not DNS entries, add a separate host alias for each Router, specifying the IP address of each Router and port of the virtual host. 

なし

Interfaces

 

Interface

Specifies the network interfaces that you want <Port> to be bound to. If you omit this element, the  port is bound on all interfaces.

For example, to specify to bind the port only to en0:

<Interfaces>
   <Interface>en0</Interface>
</Interfaces>

Determine the interfaces available on your system by running the "ifconfig -a" command.

なし

All interfaces

プロパティ

Available for Edge for Private Cloud 4.17.01 and later.

proxy_read_timeout

Sets the timeout duration, in seconds, between Message Processors and the Router. The Router drops the connection and returns an HTTP 504 response if it does not get a response from the Message Processor before this duration expires.  

The value of proxy_read_timeout should be greater than the target timeout value used by the Message Processor. This ensures that the Router does not timeout before the Message Processor has had time to return a response. The default target timeout for the Message Processor is 55 seconds, 55000 milliseconds, as defined by the   conf_http_HTTPTransport.io.timeout.millis token for the Message Processor.

57

keepalive_timeout

Sets the timeout duration, in seconds, between the client and the Router when the client makes a request that contains the Keep-Alive header. The Router keeps the connection open until the duration expires.

The Router will not close the connection if it is currently waiting for a response from the Message Processor. The timeout begins only after the Router returns the response to the client.  

65

ssl_ciphers

Sets the ciphers supported by the virtual host, overriding the defaults ciphers set on the Router. 

See the section "Specifying the TLS ciphers and protocols supported by the virtual host for Edge 4.16.01 and later" above for information on setting this property. It uses the same syntax as the token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

HIGH:!aNULL:
!MD5:
!DH+3DES:
!kEDH

ssl_protocols

Sets the TLS protocols supported by the virtual host, as a space delimited list, overriding the defaults protocols set on the Router.  

Note: If two virtual hosts share the same port, they must set ssl_protocols to the same protocols. Meaning, virtual hosts sharing the same port must support the exact same protocols.

See the section "Specifying the TLS ciphers and protocols supported by the virtual host for Edge 4.16.01 and later" above for information on setting this property. It uses the same syntax as the token conf_load_balancing_load.balancing.driver.server.ssl.protocols

TLSv1 TLSv1.1 TLSv1.2

proxy_request_buffering

Enables (on) or disables (off) buffering of the request body. When buffering is on, the Router buffers the entire request body before sending it to the Message Processor. If there is an error, the Router can retry a different Message Processor.

If off, buffering is disabled and the request body is sent to the Message Processor immediately as it is received. If there is an error, the Router does not retry the request to another Message Processor. 

on

proxy_buffering

Enables (on) or disables (off) buffering of the response. When buffering is on, the Router buffers the response. When buffering is off, the response is passed to the client synchronously, immediately as it is received by the Router. 

on

SSLInfo

 

Enabled

Enables one-way TLS/SSL. You must have defined a keystore containing the cert and private key.

false

ClientAuthEnabled

Enables two-way, or client, TLS between Edge (server) and the app (client) making the request. Enabling two-way TLS requires that you set up a truststore on Edge that contains the cert from the TLS client. 

false

KeyStore

The name of the keystore on Edge.

Apigee recommends that you use a reference to specify the keystore name so that you can change the keystore without having to restart Routers.

なし

Yes if Enabled is true

KeyAlias

The alias specified when you uploaded the cert and private key to the keystore. You must specify the alias name literally; you cannot use a reference.

なし

Yes if Enabled is true

TrustStore

The name of the truststore on Edge that contains the certificate or certificate chain used for two-way TLS. Required if <ClientAuthEnabled> is true.

Apigee recommends that you use a reference to specify the truststore name so that you can change the truststore without having to restart Routers.

なし

IgnoreValidationErrors

If true, specifies to ignore TLS certificate errors. This is similar to the "-k" option to cURL.

This option is valid when configuring TLS for Target Servers and Target Endpoints, and when configuring virtual hosts that use 2-way TLS.

false

Ciphers

For Edge for Private Cloud version 4.15.07 and earlier only. See the sections above, "Specifying the TLS ciphers and protocols supported by the virtual host for Edge 4.16.01 and later" or "Setting virtual host parameters for Edge version 4.17.01 and later" if you are using version 4.16.01 or later.

Specifies the ciphers supported by the virtual host. If no ciphers are specified, then all ciphers available for the JVM will be permitted.

To restrict ciphers, add the following elements:

<Ciphers>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>    
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
</Ciphers>

All supported by the JVM

Protocols

For Edge for Private Cloud version 4.15.07 and earlier only. See the sections above, "Specifying the TLS ciphers and protocols supported by the virtual host for Edge 4.16.01 and later" or "Setting virtual host parameters for Edge version 4.17.01 and later" if you are using version 4.16.01 or later.

Specifies the protocols supported by the virtual host. If no protocols are specified, then all protocols available for the JVM will be permitted.

To restrict protocols, add the following elements:

<Protocols>
 <Protocol>TLSv1</Protocol>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>SSLv2Hello</Protocol> 
</Protocols>

All supported by the JVM

Creating a virtual host that uses HTTP

To create a virtual host that uses the HTTP protocol, perform the following:

  1. Create the virtual host by using the Create a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node:

    $ curl -X POST -H "Content-Type:application/xml" \
    http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
    -d '<VirtualHost name="newVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Interfaces/>
         <Port>9008</Port>
       </VirtualHost>' \
    -u email:password
  2. Create the DNS record for the virtual host that matches the host alias.
  3. If you have any existing API proxies, add the virtual host to the <HTTPConnection> element in the Proxy Endpoint. The virtual host is added automatically to all new API proxies.

    See Updating an API proxy after creating a virtual host in Virtual hosts.
    All virtual hosts are automatically added to all new API proxies. Therefore, if you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

After updating an API proxy to use the virtual host, and creating the DNS record for the host alias, access the API proxy as shown below:

http://api.myCompany.com/v1/{project-base-path}/{resource-path}

例:

http://api.myCompany.com/v1/weather/forecastrss?w=12797282

Creating a virtual host that uses HTTPS

This example specifies the keystore to the virtual host by using a reference. Using a reference allows you to change the keystore without having to restart Routers. 

Use the following procedure to create the virtual host:

  1. Create and configure a keystore named myTestKeystore by using the procedure described here: Keystores and Truststores. Ensure that the keystore uses an alias name of myKeyAlias for the cert and private key.
  2. Use the following POST API call to create the reference named keystoreref to the keystore you created above:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="keystoreref">
        <Refers>myTestKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password

    The reference specifies the name of the keystore and the reference type as KeyStore.

    Use the following GET API call to view the reference:

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
  3. Create the virtual host  by using the Create a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node.

    Make sure to specify the correct keystore reference and key alias:

    $ curl -X POST -H "Content-Type:application/xml" \
    http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
    -d '<VirtualHost  name="newTLSTrustStore2">
          <HostAliases>
            <HostAlias>apiTLS.myCompany.com</HostAlias>
          </HostAliases>
          <Interfaces/>
          <Port>9005</Port>
          <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>ref://keystoreref</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
          </SSLInfo>

      </VirtualHost>' \
    -u email:
    password

    If you are performing two-way TLS with the client, then set <ClientAuthEnabled> to true and specify the truststore using the <TrustStore> element. The client must be configured correctly for two-way TLS, meaning Edge has a truststore containing the client's cert and certificate chain. Create the truststore by using the procedure described here: Keystores and Truststores
  4. Create a DNS record for the virtual host  that matches the host alias.
  5. If you have any existing API proxies, add the virtual host to the <HTTPConnection> element in the ProxyEndpoint. The virtual host is added automatically to all new API proxies.

    See Updating an API proxy after creating a virtual host in Virtual hosts.
    All virtual hosts are automatically added to all new API proxies. Therefore, if you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

After updating an API proxy to use the virtual host, and creating the DNS record for the host alias, you can access the API proxy as shown below:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

例:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Creating and modifying references to a keystore or truststore

You can optionally configure the virtual host to use a reference to the keystore or truststore instead. The advantage to using a reference is that you can update the reference to point to a different keystore or truststore to update the TLS cert without having to restart a Router.    

You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore.

If your virtual host currently uses literal keystore or truststore names, you can convert the virtual hosts to use references. However, after you update the virtual hosts to use references, you must restart the Edge Routers, one at a time. 

For example, shown below is a virtual host that uses a reference to the keystore:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Use the following POST API call to create the reference named keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

The reference specifies the name of the keystore and its type.

Use the following GET API call to view the reference:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

To later change the reference to point to a different keystore, ensuring that the alias has the same name, use the following PUT call:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

Modifying a virtual host

Use this procedure to modify the virtual host settings except those that specify the keystore, alias, and truststore. Changing those properties can require a Router restart depending on how you specified them. See Update a TLS certificate for more. 

If you change the TLS settings of an existing virtual host for Edge for Private Cloud versions 4.16.01 and 4.16.05 only, and do not change the port number of the virtual host, then you have to stop the Router and remove any cached configuration files. After removing the files, you can restart the Router.

To modify a virtual host, perform the following:

  1. Update the virtual host by using the Update a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node. You must specify the complete definition of the virtual host in the request body, not just the elements that you want to change. In this example, you change the port number of the virtual host from 9008 to 9009:

    $ curl -X PUT -H "Content-Type:application/xml" \
    http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts/{vhost_name} \
    -d '<VirtualHost name="newVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Interfaces/>
         <Port>9009</Port>
       </VirtualHost>' \
    -u email:password
  2. For Edge for Private Cloud versions 4.16.01 and 4.16.05 only, If you modify an existing virtual host, and you either enable TLS or disable TLS without changing the port number, then:
    1. Stop the Router:
      > /opt/apigee/apigee-service/bin/apigee-service edge-router stop
    2. Delete any files in /opt/nginx/conf.d
      > rm -f /opt/nginx/conf.d/*
    3. Start the Router:
      > /opt/apigee/apigee-service/bin/apigee-service edge-router start
    4. Repeat for all Routers.

Deleting a virtual host

Before you can delete a virtual host from an environment, you must update any API proxies that reference the virtual host to remove the reference. See Virtual hosts for more. 

To delete a virtual host, perform the following:

  1. Delete the virtual host by using the Delete a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node:

    $ curl -X DELETE \
    http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts/{vhost_name} \
    -u email:password

Help or comments?