You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/system-administration/options-configuring-tls). 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]
> **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](https://nodejs.org/api/tls.html). For more information, see [Understanding Edge support
> for Node.js modules](https://docs.apigee.com/api-platform/nodejs/understanding-edge-support-nodejs-modules).

**Learn more:**

- [About TLS/SSL](https://docs.apigee.com/api-platform/system-administration/about-ssl)
- [Using TLS with Edge](https://docs.apigee.com/api-platform/system-administration/using-ssl-edge)
- [About virtual hosts](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts)
- [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores)
- [API proxy configuration reference](https://docs.apigee.com/api-platform/reference/api-proxy-configuration-reference)

## 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:

1. Login to the Edge management UI at <https://enterprise.apigee.com>.
2. Select the name of the API proxy to update.
3. Select the **Develop** tab.
4. Under **Target Endpoints** , select **default**.
5. 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]
> **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>`.

6. Configure a truststore as described below in [About TLS configuration with the backend](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-edge-backend-service#about-tls-config).
7. 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](https://docs.apigee.com/api-platform/reference/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](https://docs.apigee.com/api-platform/deploy/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:

1. By default, Edge does not validate the backend cert. You must create a truststore to configure Edge to validate the cert.
2. 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:

1. Create a truststore on Edge.
2. 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.
3. Add the truststore to the TargetEndpoint or TargetServer definition.

> [!NOTE]
> **Note:**You are responsible for updating the truststore when a cert expires.

See [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/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](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host#creatingandmodifyingreferencestoakeystoreortruststore).

> [!WARNING]
> **Warning:** Another option is to specify the literal name of the keystore and truststore in the TargetEndpoints or TargetServer definition. With literal names, depending on the configuration, you might have to redeploy proxies, contact Apigee Support (Cloud), or restart Message Processors (Private Cloud). See [Update a TLS certificate](https://docs.apigee.com/api-platform/system-administration/update-or-replace-ssl-certificate) for more.

### 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:

1. Update the TargetEndpoint or TargetServer definition to use a reference.
2. Restart the Edge Message Processors:
   - **For Public Cloud** customers, contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support) to restart the Message Processors.
   - **For Private Cloud** customers, restart the Edge Message Processors one at a time.
3. 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]
> **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:

1. **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](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores). For this example, if you have to create a truststore, name it **myTrustStore**.
2. **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
   ```
3. 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.

> [!NOTE]
> **Note:** Apigee provides all Cloud customers with a cert when they create an account so that the customer can get up and running quickly with Edge. All Cloud customers get a copy of the same Apigee-provided cert. If you are doing two-way TLS to the backend, you cannot use the Apigee-provided cert because it cannot be used to uniquely identify the owner of the API proxy connecting to the backend. Instead, you should obtain your own cert for your organization.

### 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](https://docs.apigee.com/api-platform/troubleshoot/support) to enable this feature.

### Configuring two-way TLS

To configure two-way TLS:

1. Create the keystore on Edge, and upload the cert and private key, by using the procedure described here: [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores). For this example, create a keystore named **myTestKeystore** that uses an alias name of **myKey** for the cert and private key.
2. 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
   ```
3. **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](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores). For this example, if you have to create a truststore name it **myTrustStore**.
4. **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
   ```
5. 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. Login 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 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]
      > **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.

   7. 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](https://docs.apigee.com/api-platform/reference/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](https://docs.apigee.com/api-platform/system-administration/using-sni-edge) for more.