Getting your subdomain working on Apigee for secure API calls

davidafreeman · ‎10-25-2019

Getting your subdomain working on Apigee for secure API calls

This is a quick article for newbies to Apigee who want secure API calls (port 443) to their company domain (e.g. yourCompany.com) going through Apigee Edge.

We will deal with the 101 of first-time loading certificates, working with TLS Keystores, and Virtual Hosts. It should be especially helpful for those who have common errors when working with these components the first time.

So if you’re trying to set-up your Apigee gateway to accept calls from api.yourCompany.com, then this is the article for you.

We will go through;

Certificates – making sure they are “Apigee-ready”
TLS Keystores – how to ensure a valid “Apigee-ready” certificate is loaded (creating an Alias)
Virtual Hosts – how to successfully create a vHost using that “Apigee-ready” certificate (i.e. Keystore)

Pre-requisites

Here are the following pre-requisites for this article;

Paid Apigee plan (you can’t add vHosts without a paid plan)
Openssl – I run a Windows machine and run this tool; https://slproweb.com/products.html
Notepad++
Registered DNS record
Certificate Authority you can use to give you a signed certificate and private key.

Certificates

Certificates can be painful and finicky to work with at the best of times, so we will go into some detail to ensure that your certificate will load and be valid in Apigee. In this example I will be using GoDaddy, but any valid Domain and Certificate Authority (CA) will do.

1.Add “api” subdomain

a)You need to add a valid subdomain to your existing domain so that API calls can hit where your subdomain is hosted.
b)Assuming you’ve already got a valid domain name (e.g. yourCompany.com), add a subdomain (e.g. api.yourCompany.com) to your DNS record;
Name = api Type = CNAME Value = [org-name]-prod.apigee.net (this is your default Apigee Org)

Note: if your using GoDaddy, do not use their Forwarding SUBDOMAIN option, as this is a URL forwarder and uses an intermediary URL shortener to forward requests. I personally think this is dodgy.

2.Create an SSL certificate for that subdomain

a)Buy a signed SSL certificate from a CA and ensure that it is set-up for your subdomain (e.g. api.yourCompany.com).
b)Make sure you save the CSR and Private Key. In GoDaddy this screen is presented to you early on, and it’s easy to skip it. Make sure these are saved somewhere securely but accessible.
c)Download the certificate.

3.Get certificate Apigee-ready

Depending who you go through, you may have a few different files to work with and you’ll need a certificate chain in the PEM format for it work with Apigee. In Go Daddy I was given these files;
- CRT root certificate file root certificate
- CRT intermediate certificate file
- PEM certificate file
- CSR file
- KEY private key file (unencrypted)
a)Convert your CRTs (or .cer, or .der) files to PEM text format using openssl;

openssl x509 -inform der -in certificate.cer -out certificate.pem text

b)Combine root and intermediary certificates - Now they are in PEM format, you’ll need to combine your root and intermediate certificates, if not already available. Open notepad++ and add the intermediate first and the root at the bottom;

 -----BEGIN CERTIFICATE----- 
Your intermediate certificate (the one for api.yourCompany.com) 
-----END CERTIFICATE----- 
-----BEGIN CERTIFICATE----- 
Your root certificate 
-----END CERTIFICATE-----

c)Strip out any hidden characters from certificate - (I’ve seen certificates and private keys that have hidden characters that prevent them being loaded), by using notepad++ and saving the file. Go to menu Encoding > Convert to UTF-8.
You now have a valid PEM file with a full certificate chain.
d)Strip out any hidden characters from your private key using notepad++.
e)Encrypt your KEY file. It’s important your keep your private key secret and secure. Use OpenSSL to encrypt your key file;

 openssl rsa -des3 -in unencrypted.key -out encrypted.key

Now enter and then re-enter your password (do not forget it!)

Keystore

Now that you have your certificate and private key Apigee-ready, it’s time to load them into a TLS Keystore so that it can be used by your virtual host when you set that up to terminate secure API calls to you Apigee org.

1. Create TLS Keystore

a.From the Apigee Edge UI, navigate to Admin > TLS Keystores.
b.Make sure you’re on the right environment (in this case prod), and add a Keystore.
c.Enter the name of your keystore, and once added create an alias.
d.Now give your alias a name (it’s recommended you choose a name that the certificate domain is registered against), choose Certificate and Key, load your Apigee-ready certificate and key, and enter your key password. Hit Save.
Common error: “Failed to parse the Key file” – This will most likely mean your key file has hidden characters you need to remove as per step 3 d). See here for more details; https://community.apigee.com/questions/66567/failed-to-parse-the-key-file-when-uploading-a-key.html
Note: Do not bother testing the Keystore at this stage. As your certificate is not attached to any host, there is no way a connection test can be achieved and you will just get an error saying “Invalid Truststore. Unable to find valid certification path to requested target”.

Virtual Host

After we’ve loaded the certificate and the key successfully into a TLS Keystore, it’s time to associate that certificate to a virtual host.

1.Create Virtual Host

a.From the Apigee Edge UI, navigate to Admin > Virtual Hosts.
b.Ensure you’re on the right environment, then add Virtual Host. {insert add vhhost1}
c.Enter a name, your base URL (including the https, e.g. https://api.yourCompany.com), host alias (e.g. api.yourcompany.com).
d.Select your keystore, and keystore alias that you just created. Hit Create.

Common error: “Virtual host creation/update failed due to keystore cert validation error. Cert is invalid or cannot be trusted by java trust anchors or CAs”. This generally occurs when your certificate chain is set-up incorrectly in your PEM file. You need to have the root and intermediary certificates in the one PEM file so the chain of trust can be established, and they also need to be placed in the right order in the PEM file too (root at the bottom, and intermediaries cascading above it)

2.Test your Keystore

a.Go back to the TLS Keystore you created and hit the test button.
b.Enter the subdomain you need to test (e.g. api.yourcompany.com), select port 443, and hit test! If you’ve done all the steps above successfully you’ll get a Success!

Well done, you’re now ready to start getting those API calls through securely to your Apigee org through your company domain!

I hope this instruction has helped you get your first, and most important virtual host set-up with your primary certificate for secure API traffic.

Certificate, Keystore, and Virtual Host 101

Getting your subdomain working on Apigee for secure API calls

Certificates

Keystore

Virtual Host