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

To configure TLS, you have to configure the following on Edge:

  • Repositories for TLS keys and certs:
    • Keystores: Contains an TLS certificate and private key used to identify the entity during TLS handshaking. When you create the keystore and upload the TLS cert, you specify an alias name used to reference the cert/key pair.
    • Truststores: contains certificates used to verify certificates received as part of TLS handshaking. A truststore is usually not required. It is used when you have to validate self-signed certificates received from the TLS server, or certificates that are not signed by a trusted CA. It is also required when performing two-way TLS when Edge acts as the TLS server.  
  • API proxies to use the certs in keystores and truststores:
    • Virtual Hosts: 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. As part of configuring a virtual host, you optionally specify a keystore and truststore as part of configuring TLS.
    • Target Endpoints/Target Servers: defines endpoint of the backend system accessed by an API proxy. As part of configuring a target endpoints/target servers, you configure it to support the TLS requirements of the backend system, including ​specifying a keystore and truststore.

See also:

Cloud vs. Private Cloud configuration differences

Both Edge cloud and Edge for Private Cloud let you create and configure keystores and truststores. 

The biggest difference between the two is that in a cloud-based installation of Edge, Apigee Support configures virtual hosts for you. For Private Cloud, you create and configuring virtual hosts.

Both cloud and Private Cloud customers can create and configure target endpoints and target servers.

TLS configuration options for virtual hosts and target endpoints/target servers

The way you configure TLS for virtual hosts and target endpoints/target servers has an impact on:

  • Flexibility of use
  • Handling of expired certs

The following table shows the three way to configure TLS for a virtual hosts and target endpoints/target servers, and contains links to detailed information on how to perform the configuration. 

Config 
type

Example

Notes

Direct

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>
    true
  </ClientAuthEnabled>
  <KeyStore>myTestKeystore</KeyStore> 
  <KeyAlias>myKeyAlias</KeyAlias> 
  <TrustStore>freetrial</TrustStore>
</SSLInfo>

Specify static names for the keystore, cert/key pair alias, and truststore.

Advantages: Simplest form of configuration.

Disadvantages: The names of the keystore, cert alias, and truststore are static. If you have to change any of them, you have to edit and redeploy the proxy. 

For more, see:

Flow vars

<SSLInfo>
  <Enabled>{ssl.enabled}</Enabled>
  <ClientAuthEnabled>
    {ssl.clenabled}
  </ClientAuthEnabled>
  <KeyStore>{ssl.keystore}</KeyStore>
  <KeyAlias>{ssl.keyAlias}</KeyAlias>
  <TrustStore>{ssl.trustStore}</TrustStore>
</SSLInfo>

Use flow variables to specify some or all of the TLS/SSL information. Lets you pass values as part of the request to specify the TLS/SSL information used in that request.

For example, you are connecting to a backend endpoint over TLS/SSL and, depending on whether you are connecting to the test or prod environment of that backend server, you need to use the appropriate keystore and truststore. See this article for more examples.

Advantages: Lets you dynamically control the TLS/SSL information per request without having to redeploy the API proxy. 

Disadvantages: Works only for target endpoints/target servers. It is not available for use with virtual hosts.

For more, see:

Refs

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>
    true
  </ClientAuthEnabled>
  <KeyStore>ref://mykeystore</KeyStore>
  <KeyAlias>freetrial</KeyAlias>
  <TrustStore>ref://mytruststore</TrustStore>
</SSLInfo>

Use a reference to the keystore and/or truststore.

Advantages: Lets you change the reference to the keystore or truststore without having to redeploy the proxy. If the cert expires, you can update the reference to the keystore or truststore without having to restart a Router or Message Processor.

Disadvantages: Can only specify a reference to the keystore and truststore, but not to the alias.

For more, see:

Updating a cert or replacing an expired cert

At some time, you might have to replace or update a cert. For example, all TLS certs have an expiration date. When you configure a virtual host or target endpoint/target server to use TLS, and the specified cert expires, all API calls through the virtual host or target endpoint/target server will fail.

You cannot update an existing keystore to add a new certificate. You must create a new keystore when updating a certificate.

The following table list the ways to update a cert based on the three different ways to configure a virtual host or target endpoint/target server:

Config 
type

How to update/replace a cert

Private Cloud

Cloud

Direct and flow vars Create a new keystore/truststore with the new cert.

Update the virtual host and restart the Routers.

If the keystore and truststore are referenced directly from the TargetEndpoint definition, then you must redeploy the proxy.

For virtual hosts, contact Apigee Support.

If the keystore and truststore are referenced directly from the TargetEndpoint definition, then you must redeploy the proxy.

Direct and flow vars

Delete the keystore/truststore and recreate it with same name.

No virtual host update required, no Router restart necessary.

If the keystore is used for two-way TLS between Edge and the backend service, restart the Message Processors.

For virtual hosts, contact Apigee Support.

If the keystore is used for two-way TLS between Edge and the backend service, contact Apigee Support.

 

Refs

For a keystore, create new keystore with a new name and an alias with same name as the old alias. 

For a truststore, create a truststore with a new name. 

Update the reference to the keystore or truststore. No Router or Message Processor restart is necessary.

For virtual hosts, contact Apigee Support.

Update the reference to the keystore or truststore.

See also:

Help or comments?