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 virtual hosts for the Cloud

Self-service virtual hosts for Edge for the Cloud require that you enable TLS. For information about the Beta release of the self-service TLS feature, see the TLS/SSL.

About configuring a virtual host

A Cloud customer with a paid account can create a virtual host in an organization. The user creating the virtual host must be in the role of organization administrator, or in a custom role with permissions to modify a virtual host. Users in other roles do not have authorization to create virtual hosts.

Free and trial accounts cannot create or modify virtual hosts and are limited to the virtual hosts created for them at Edge registration time. For more information on Edge pricing plans, see https://apigee.com/api-management/#/pricing.

The following table summarizes the requirements for creating a virtual host:

Category Requirement Description
Account type Paid Free and trial accounts cannot create or modify virtual hosts.
User role organization admin Only an org admin can create a virtual host, or a user in a custom role that has permissions to modify a virtual host.
Number of virtual hosts 10 maximum

You are limited to a maximum of 10 virtual hosts per organization/environment in the Cloud.

Note: There is no limit to the number of virtual hosts in the Private Cloud.

Most organizations/environments use two virtual hosts: one for HTTP and one for HTTPS access. You might need additional virtual hosts if your organization/environment allows access using different domain names.

If you require more than 10 virtual hosts, and have a paid support plan, contact Apigee Support.

Port 443

You can only create a virtual host on port 443.

Note that you can create multiple virtual hosts on port 443 as long as they have unique host aliases and all support TLS.

If you require a different port, and have a paid support plan, contact Apigee Support.

TLS Required

You can only create a virtual host that supports TLS over HTTPS. You must have already created a keystore, and optionally a truststore, containing your TLS cert and key.

Self-signed certs are not allowed. You must have a cert signed by a CA.

If you require HTTP access, contact Apigee Support.

Host alias Unique in the organization and environment The host alias does not exist for another organization/environment combination.
Domain name Owned by customer

You must own the domain name specified in the virtual host. Edge checks to make sure that the domain name, as defined by the host alias, matches the metadata in the TLS cert.

Specifically, Edge checks the following information in the cert:

  • CN - Common Name
  • SAN - Subject Alternative Name

Wildcards are allowed in the SAN or CN, for example, *.myco.net.

Edge also validates that the cert has not expired.

Client app SNI support All client apps accessing the virtual host must support SNI.

If you have older apps that do not support SNI, and you have paid for Apigee Support, then contact Apigee Support to create the virtual host on a port other than 443. After creation by Apigee Support, you can later modify the virtual host.

Note: SNI support is required by all apps used with free and trial accounts.

Defining a virtual host for one-way TLS

To create a virtual host, create an XML object that defines the virtual host. For example, the following XML object defines a virtual host for one-way TLS:

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

In this definition you:

  • Specify the name as myTLSVHost. Use the name to reference the virtual host in an API proxy or in an API call.
  • Specify the host alias as api.myCompany.com. This is the publicly facing domain used to access your APIs as defined by a DNS definition and CNAME record.
  • Specify the port number as 443. If omitted, by default the port is set to 443.
  • Enable TLS as required.

    The <Enable> element is set to true to enable one-way TLS, and the and <KeyStore> elements specify the keystore and key alias used by the TLS connection.

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

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

Note that there are additional properties that you can set in the virtual host. For a reference for all properties, see Virtual host property reference.

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

When configuring a virtual host to support TLS, you specify a keystore by using a reference. A reference is a variable that contains the name of the keystore or truststore, rather than specifying the keystore or truststore name directly, as shown below:

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>

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. See Working with references for more on creating and modifying references.

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, meaning you have to contact Apigee Suport. Apigee strongly recommends that you use references to keystores and truststores in a virtual host and do not use direct references.

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.

Defining a virtual host for two-way TLS

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

To create a virtual host for two-way TLS, create an XML object that defines the virtual host:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTestTruststoreRef</TrustStore> 
    </SSLInfo>
</VirtualHost>

In this definition you:

  • Enable two-way TLS by setting <ClientAuthEnabled> to true.
  • Specify a truststore using the <TrustStore> element. The truststore holds the client's certificate and, optionally, certificate's CA chain.

Creating a virtual host

Use the following procedure to create the virtual host:

  1. Create a DNS entry and CNAME record for your publicly facing domain, api.myCompany.com for this example, that points to [org]-[environment].apigee.net.
  2. Create and configure a keystore, named myTestKeystore in this example, by using the procedure described here: Creating keystores and truststore for the Cloud using the Edge UI. For this example, ensure that the keystore uses an alias name of myKeyAlias for the cert and private key.
  3. Upload your cert and key to the keystore. Ensure that the domain name specified by your cert matches the host alias that you want to use for the virtual host.
  4. Create a reference to the keystore by using the Edge UI or API. See Working with references for more on creating and modifying references.

    For example, use the following POST API call to create the reference named myTestKeystoreRef 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="myTestKeystoreRef">
       <Refers>myTestKeystore</Refers>
       <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u 
    orgAdminEmail:password

    The reference specifies the name of the keystore and the reference type as KeyStore.
  5. Create the virtual host by using the Create a Virtual Host API. Make sure to specify the correct keystore reference and key alias:

    curl -X POST -H "Content-Type:application/xml" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
    -d '<VirtualHost  name="myTLSVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Port>443</Port>
         <SSLInfo>
           <Enabled>true</Enabled>
           <ClientAuthEnabled>false</ClientAuthEnabled>
           <KeyStore>ref://myTestKeystoreRef</KeyStore>
           <KeyAlias>myKeyAlias</KeyAlias>
         </SSLInfo>
     </VirtualHost>' \
    -u 
    orgAdminEmail: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: Creating keystores and truststore for the Cloud using the Edge UI.
  6. 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 About virtual hosts.

    Caution: 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 entry and CNAME record for the host alias, you can access the API proxy as shown below:

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

For example:

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

Modifying a virtual host

Paid customers can use the Update a Virtual Host API to update a virtual host. This API lets you set all of the properties for the virtual host described at Virtual host property reference.

Free and trial accounts cannot create or modify virtual hosts and are limited to the four virtual hosts created for them at Edge registration time.

Caution: Before you modify a virtual host:

  • Ensure that the virtual host uses references to set <KeyStore> and <TrustStore>. Do not set them directly to the name of a keystore or truststore.
  • If the <KeyStore> and <TrustStore> use references, update the value of the reference to change the keystore or truststore. If you want to change <KeyStore> and <TrustStore> to use a different reference variable, you must work with Apigee Support because this change requires a Router restart.
  • If the <KeyStore> and <TrustStore> are directly set to the name of a keystore or truststore, you must work with Apigee Support to convert them to references. See "Updating a virtual host to use references to the keystore and truststore" in Configuring TLS access to an API for the Cloud for more.
  • If the virtual host already has a value for <KeyAlias>, do not change it. The new keystore must use an alias with the same name as the current alias. To change the alias name, you must work with Apigee Support.
  • You cannot enable TLS on a virtual host using port 80.
  • You cannot disable TLS on a virtual host using port 443.
  • If Apigee Support configured the virtual host for you to use a port other than 443, then you can still update the virtual host but cannot change the port. A port other than 443 is typically required if your app does not support SNI. If you need to change the port, contact Apigee Support.

When you modify the virtual host, Edge performs a validation similar to when you create a virtual host. That is, on a modify, Edge validates that:

  • The domain as specified by the host alias is not used in another organization and environment.
  • You own the domain name. Specifically, Edge checks that the following information in the cert matches the host alias:
    • CN - Common Name
    • SAN - Subject Alternative Name
    • Edge validates that the cert has not expired.

To modify a virtual host by using the Edge API, perform the following:

  1. Update the virtual host by using the Update a Virtual Host API. 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 set the value of the proxy_read_timeout property:
    curl -X PUT -H "Content-Type:application/xml" \
    https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
    -d '<VirtualHost  name="myTLSVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Port>443</Port>
         <SSLInfo>
           <Enabled>true</Enabled>
           <ClientAuthEnabled>false</ClientAuthEnabled>
           <KeyStore>ref://myTestKeystoreRef</KeyStore>
           <KeyAlias>myKeyAlias</KeyAlias>
         </SSLInfo>
         <Properties>
           <Property name="proxy_read_timeout">50</Property>
         </Properties>

     </VirtualHost>' \
    -u 
    orgAdminEmail:password

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 Updating an API proxy after creating a virtual host in About virtual hosts.

To delete a virtual host, perform the following:

  1. Delete the virtual host by using the Delete a Virtual Host API:
    curl -X DELETE \
    https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
    -u 
    orgAdminEmail:password

Setting additional virtual host parameters

You can set additional TLS properties for an individual virtual host, such as TLS cipher, by using the <Properties> child tag of the <VirtualHost> tag. These tags are described in the table below.

For example:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</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_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

Cloud customers cannot set the ssl_protocols property of the virtual host.

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 supports 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 <BaseUrl> attribute. In this example, the value "http://myCo.com" appears in the Edge UI:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <BaseUrl>http://myCo.com</BaseUrl>     
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

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

 

Help or comments?