Configure client SSL from Apigee API Platform to your backend service

A most common mechanism used to secure traffic from Apigee to your backend service is Client SSL. Client SSL provides authentication and encryption of all messages flowing over the network from Apigee to your services.

Step 1: Generate client credentials

To configure client SSL for mutual authentication between Apigee and your backend server, you require a public/private key pair and an X.509 certificate. The certificate can be issued by a certificate authority, or it can be self-signed by the private key that you generate. If you have access to a CA, follow instructions provided by your CA for generating keys and issuing certificates. If you do not have access to a CA, you can generate a self-signed certificate using one of the many publicly available free tools, such as openssl.

Supported key formats are:

• PEM
• DER
• PKCS12
• JKS (Can be imported directly without creating keystore--bypassing Step 2, below)

Apigee supports key sizes up to 2048 bits.

Step 2: Create a JAR file containing your keystore

Create a JAR file with your key pair, certificate, and a manifest. The JAR file must contain the following files and directories:

• /META-INF/descriptor.properties
• myCert.pem
• myKey.pem (Passphrase is optional)

Create a directory called /META-INF. Create a file called descriptor.properties in /META-INF with the following contents:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Generate the JAR file containing your key pair and certificate:

$ jar -cf myKeystore.jar myCert.pem myKey.pem

Add descriptor.properties to your JAR file:

$ jar -uf myKeystore.jar META-INF/descriptor.properties

Step 3: Create keystore on the API Platform

You must upload the keystore file to an environment in your Apigee organization, and then reference this file in your target endpoint configuration.

First check your environment for any existing keystores:

$ curl -u myname:mypass -X GET https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores

[ "freetrial" ]

Check the contents of the keystore. At a minimum, you should see a single server SSL certificate--the default certificate that Apigee provides for free trial accounts.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial

{
  "certs" : [ "wildcard.apigee.net.crt" ],
  "keys" : [ "freetrial" ],
  "name" : "freetrial"
}

Create your own keystore in the environment:

Sample request:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores -H "Content-Type: text/xml" -d '<KeyStore name="myKeystore"/>'

Sample response:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

Step 4: Upload keystore JAR to the API Platform

Sample request:

$ curl -u myname:mypass -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}&password={key_pass}

Verify that your keystore uploaded properly:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore

Sample response:

{  "certs" : [ "myCertificate" ],
  "keys" : [ "myKey" ],
  "name" : "myKeystore"
}

You now have a private key available for mutual authentication between the specified environment in your organization on the API Platform and your backend service. If you are using a self-signed certificate instead of a certificate issued by a CA, then you must import the self-signed certificate to the trust store on the target server. To do so, refer to the instructions for the target server where your backend service is deployed.

Step 5: Configure TargetEndpoint for client SSL

In the TargetEndpoint configuration for your API proxy, add the following elements to the HTTPConnection configuration:

<ClientAuthEnabled>true</ClientAuthEnabled>
<KeyStore>myKeystore</KeyStore>
<KeyAlias>myKey</KeyAlias>

For example:

<TargetEndpoint name="default">
  <HttpTargetConnection>
    <SSLInfo>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HttpTargetConnection>
</TargetEndpoint>

If no ciphers are specified, then all ciphers available for the JVM will be permitted.

To restrict ciphers, add the following elements to <SSLInfo>:

<Ciphers>
	<Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
	<Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

If no protocols are specified, then all protocols available for the JVM will be permitted.

To restrict protocols, add the following elements to <SSLInfo>

<Protocols>
    <Protocol>TLSv1</Protocol>
    <Protocol>SSLv2Hello</Protocol>
</Protocols>

$ curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u myname:mypass

$ curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias= myTruststore-alias" \
-u myname:mypass 

<TargetEndpoint name="default">
  <HttpTargetConnection>
    <SSLInfo>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
    <URL>https ://myservice.com</URL>
  </HttpTargetConnection>
</TargetEndpoint>