Playbook : How to add customized domain and SSL certificate to Apigee virtual host?

[#1]

This article is for Apigee Edge cloud customers only.

For existing customers, if the virtual host is listing a port number > 1024, please submit a support incident for the change. If the port number is > 1024 and two-way SSL is needed, please follow below steps.

For others, please follow below steps:

Step 1

Create a keystore

curl -X POST -H "Content-Type: text/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores -d '<KeyStore name="myKeystore"/>' -u email:password 

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

For two-way SSL only, create a truststore with the same API.

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

Step 2

Create a JAR file containing the full server certificate chain and private key in PEM format. The full server certificate chain should contain server certificate, intermediate CAs, and root CA in a top-down order.

In the directory containing your key pair and certificate, i.e. myKey.pem and myCertificate.pem, create a directory called /META-INF. 

Create a file called descriptor.properties in /META-INF with below contents:
certFile=myCertificate.pem
keyFile=myKey.pem

Generate the JAR file containing your key pair and certificate:
$ jar -cf myKeystore.jar myCertificate.pem myKey.pem

Add descriptor.properties to your JAR file:
$ jar -uf myKeystore.jar META-INF/descriptor.properties 

Upload the server certificate chain and key into the keystore.

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

the -F option specifies the path to the JAR file. the alias identifies the certificate and key in the key store. the password is for the private key. Omit password if the private key has no password.

Verify the upload

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystore -u email:password

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

For two-way SSL only, upload the client certificate chain into the truststore,

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/cer... -u email:password

Step 3

Open an incident with apigee support to update the virtual host with the information: host alias, keystore name, key alias name, truststore name (two-way SSL only).

Note that an SMB customer can only have one customized certificate among the environments of customer's choice.

Reference links for detailed information regarding SSL on Apigee Edge

http://docs.apigee.com/api-services/content/keystores-and-truststores

http://docs.apigee.com/api-services/content/about-ssl

http://docs.apigee.com/api-services/content/configuring-ssl-cloud-based-edge-installation

[#2]

Great help, but unfortunately out-dated.

URL doesn't work anymore, needs to have a body with keystore name.

https://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/environments/%7Benv_name%7...

Also for consumers not very familiar with Java it would be helpful to extend it with how/where to get the jar tooling.

[edu4krishanu]

Hi,

I have the private key in .key format. How can I use to create the jar? I couldn't find any tool to convert the private key to .pem format. Please help!

Thanks,

Krish

[kotikarthickkum]

I guess we should be able to convert .key to .pem using openssl.