Configuring TLS from Edge to the backend (Cloud and Private Cloud)

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

An API proxy functions as a mapping of a publicly available endpoint to your backend service. A virtual host defines the way that the public facing API proxy is exposed to an app. For example, the virtual host determines if the API proxy can be accessed by using TLS. When you configure an API proxy, edit its ProxyEndpoint definition to configure the virtual hosts that it uses.

The TargetEndpoint is the outbound equivalent of the ProxyEndpoint. A TargetEndpoint functions as an HTTP client from Edge to a backend service. When creating an API proxy, you can configure it to use zero or more TargetEndpoints.

Note: Node.js: If your proxy target is a Node.js application, you can use the Node.js tls module to create secure connections to backend services. You make outgoing requests with the tls module the same way you would normally in Node.js. Basically, you need to add client-side keys and certificates (.pem files) to the resources/node directory and load them inside your script. For information on using the tls module and its methods, see the Node.js tls module documentation. For more information, see Understanding Edge support for Node.js modules.

Learn more:

Configuring a TargetEndpoint or TargetServer

To configure a TargetEndpoint, edit the XML object that defines the TargetEndpoint. You can edit the TargetEndpoint by editing the XML file that defines the TargetEndpoint in your API proxy, or edit it in the Edge management UI.

To use the Edge management UI to edit the TargetEndpoint:

Login to the Edge management UI at https://enterprise.apigee.com.
Select the name of the API proxy to update.
Select the Develop tab.
Under Target Endpoints, select default.

In the code area, the TargetEndpoint definition appears, similar to below:

<TargetEndpoint name="default">
  <Description/>
  <FaultRules/>
  <Flows/>
  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPTargetConnection>
    <Properties/>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Note: In the Edge UI, if <URL> specifies the HTTPS protocol, the UI does not automatically insert the <SSLInfo> block. By default, the value of <Enabled> is true and the value of <TrustStore> is empty if <URL> specifies HTTPS. Apigee strongly recommends that you add the <SSLInfo> block when configuring TLS access to the backend to explicitly set the value of <Enabled> to true and to specify the <TrustStore>.

Configure a truststore as described below in About TLS configuration with the backend.
Make any changes and save the proxy. If the API proxy has been deployed, saving it redeploys it with the new setting.

Notice that the TargetEndpoint definition contains a name property. You use the value of the name property to configure the ProxyEndpoint definition of an API proxy to use the TargetEndpoint. See API proxy configuration reference for more.

TargetEndpoints can be configured to reference a TargetServer, rather than the explicit target URL. A TargetServer configuration decouples concrete endpoint URLs from TargetEndpoint configurations. TargetServers are used to support load balancing and failover across multiple backend server instances.

Shown below is an example TargetServer definition:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer>

A TargetServer is referenced by name in the <HTTPTargetConnection> element in a TargetEndpoint definition. You can configure one or more named TargetServers, as shown below.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <LoadBalancer>
      <Server name="target1" />
      <Server name="target2" />
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

See Load balancing across backend servers for more.

About TLS configuration with the backend

Before you configure TLS access to the backend, you should understand two important points:

By default, Edge does not validate the backend cert. You must create a truststore to configure Edge to validate the cert.
Use a reference to specify the keystore or truststore used by Edge.

Both considerations are described below.

Defining a truststore to enable cert validation

When making a TLS request through a TargetEndpoint or TargetServer, Edge does not by default validate the TLS cert received from the backend server. That means Edge does not validate that:

The certificate has been signed by a trusted CA.
The certificate has not expired.
The certificate presents a common name. If there is a common name, Edge does not validate that the common name matches the hostname specified in the URL.

To configure Edge to validate the backend cert, you must:

Create a truststore on Edge.
Upload the server's cert or cert chain to the truststore. If the server certificate is signed by a third party, then you will need to upload the complete cert chain, including the root CA cert, to the truststore. There are no implicitly-trusted CAs.
Add the truststore to the TargetEndpoint or TargetServer definition.

See Keystores and Truststores for more.

For example:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Using a reference to a keystore or truststore

The example below shown how to configure a TargetEndpoint or TargetServer to support TLS. As part of configuring TLS, you specify a truststore and keystore as part of a TargetEndpoint or TargetServer definition.

Apigee strongly recommends that you use a reference to the keystore and truststore in the TargetEndpoints or TargetServer definition. The advantage to using a reference is that you only have to update the reference to point to a different keystore or truststore to update the TLS cert.

References to keystores and truststores in the TargetEndpoints or TargetServer definition work the same way as they do for virtual hosts.

Converting a TargetEndpoint or TargetServer to use a reference

You might have existing TargetEndpoint or TargetServer definitions that uses the literal name of the keystore and truststore. To convert the TargetEndpoint or TargetServer definition to use references:

Update the TargetEndpoint or TargetServer definition to use a reference.
Restart the Edge Message Processors:
- For Public Cloud customers, contact Apigee Edge Support to restart the Message Processors.
- For Private Cloud customers, restart the Edge Message Processors one at a time.
Confirm that your TargetEndpoint or TargetServer is working correctly.

Configuring one-way TLS to the backend server

When using a TargetEndpoint definition, configuring one-way TLS access from Edge (TLS client) to the backend server (TLS server) does not require any additional configuration on Edge. It is up to the backend server to configure TLS correctly.

You only need to make sure that the <URL> element in the TargetEndpoint definition references the backend service by the HTTPS protocol and that you enable TLS:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

If you are using a TargetServer to define the backend service, then enable TLS in the TargetServer definition:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
  </SSLInfo> 
</TargetServer>

Note: If you define the <SSLInfo> block in both the TargetEndpoint and the TargetServer definition, the one in the TargetServer takes precedence.

However, if you want Edge to validate the backend cert, then you must create a truststore that contains the backend cert or cert chain. You then specify the truststore in the TargetEndpoint definition:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Or in the TargetServer definition:

<TargetServer name="target1">
  <Host>mockserver.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
    <TrustStore>ref://myTrustStoreRef</TrustStore>
  </SSLInfo> 
</TargetServer>

To configure one-way TLS:

If you want to validate the backend cert, create a truststore on Edge, and upload the backend cert or CA chain, as described in Keystores and Truststores. For this example, if you have to create a truststore, name it myTrustStore.

If you created a truststore, use the following POST API call to create the reference named myTrustStoreRef to the truststore 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="myTrustStoreRef">
    <Refers>myTrustKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>' -u email:password

Use the Edge management UI to update the TargetEndpoint definition for the API proxy (or, if you define the API proxy in XML, edit the XML files for the proxy):
1. Log in to the Edge management UI at https://enterprise.apigee.com.
2. In the Edge management UI menu, select APIs.
3. Select the name of the API proxy to update.
4. Select the Development tab.
5. Under Target Endpoints, select default.
6. In the code area, edit the <HTTPTargetConnection> element to add the <SSLInfo> element. Make sure to specify the correct truststore reference and set <Enabled> to true:
```
<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>
```
7. Save the API proxy. If the API proxy has been deployed, saving it redeploys it with the new setting.

Configuring two-way TLS to the backend server

If you want to support two-way TLS between Edge (TLS client) and the backend server (TLS server):

Create a keystore on Edge and upload the Edge cert and private key.
If you want to validate the backend cert, create a truststore on Edge that contains the cert and CA chain that you received from the backend server.
Update the TargetEndpoint of any API proxies that reference the backend server to configure TLS access.

Using the key alias to specify the keystore cert

You can define multiple certs, each with its own alias, in the same keystore. By default, Edge use the first cert defined in the keystore.

Optionally, you can configure Edge to use the cert specified by the <KeyAlias> property. This lets you define a single keystore for multiple certs, then select the one you want to use in the TargetServer definition. If Edge cannot find a cert with an alias that matches <KeyAlias> then it uses the default action of selecting the first cert in the keystore.

Edge for Public Cloud users must contact Apigee Edge Support to enable this feature.

Configuring two-way TLS

To configure two-way TLS:

Create the keystore on Edge, and upload the cert and private key, by using the procedure described here: Keystores and Truststores. For this example, create a keystore named myTestKeystore that uses an alias name of myKey for the cert and private key.

Use the following POST API call to create the reference named myKeyStoreRef 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="myKeyStoreRef">
    <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/myKeyStoreRef /
-u email:password

If you want to validate the backend cert, create a truststore on Edge, and upload the cert and CA chain, as described here: Keystores and Truststores. For this example, if you have to create a truststore name it myTrustStore.

If you created a truststore, use the following POST API call to create the reference named myTrustStoreRef to the truststore 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="myTrustStoreRef">
    <Refers>myTrustKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

Use the Edge management UI to update the TargetEndpoint definition for the API proxy (or, if you define the API proxy in XML, edit the XML files for the proxy):

Login to the Edge management UI at https://enterprise.apigee.com.
In the Edge management UI menu, select APIs.
Select the name of the API proxy to update.
Select the Development tab.
Under Target Endpoints, select default.

In the code area, edit the <HTTPTargetConnection> element to add the <SSLInfo> element. Make sure to specify the correct keystore and key alias and set both the <Enabled> and <ClientAuthEnabled> elements to true:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>ref://myKeyStoreRef</KeyStore>
      <KeyAlias>myKey</KeyAlias>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

Note: If you created a truststore, include it in the <HTTPTargetConnection> element:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>ref://myKeyStoreRef</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
    …
</TargetEndpoint>

If your TargetEndpoint references a TargetServer instead of a specific URL, update the TargetServer definition to reference the new keystore and key alias. For example:

<TargetServer name="target1>
  ...
  <SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>ref://myKeyStoreRef</KeyStore>
    <KeyAlias>myKey</KeyAlias>
  </SSLInfo>
</TargetServer>

If you had to create a truststore:

<TargetServer name="target1">
  ...
  <SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>ref://myKeyStoreRef</KeyStore>
    <KeyAlias>myKey</KeyAlias>
    <TrustStore>ref://myTrustStoreRef</TrustStore>
  </SSLInfo>
</TargetServer>

You do not have to save the API proxy if you update a TargetServer definition.

Save the API proxy. If the API proxy has been deployed, saving it redeploys it with the new setting.

For more information on the options available in the <TargetEndpoint>, including using variables to supply TargetEndpoint <SSLInfo> values, see API proxy configuration reference.

Enabling SNI

Edge supports the use of Server Name Indication (SNI) from Message Processors to target endpoints in Apigee Edge for Cloud and for Private Cloud deployments.

For Edge for the Private Cloud, to be backward compatible with your existing target backends, Apigee disabled SNI by default. If your target backend is configured to support SNI, you can enable this feature. See Using SNI with Edge for more.