Update a TLS certificate for the Private Cloud

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

The method that you use to specify the name of the keystore and truststore in the virtual host or target endpoint/target server determines how you perform the cert update. You can specify the name of the keystore and truststore by using:

References - preferred
Direct names
Flow variables

Each of these methods has different repercussions on the cert update process, as described in the following table.

Config type	How to update/replace a cert	How to update the virtual host, target endpoint/target server
Reference (recommended)	For a keystore, create new keystore with a new name and an alias with same name as the old alias. For a truststore, create a truststore with a new name.	Update the reference to the keystore or truststore. No Router or Message Processor restart is necessary.
Flow vars (target endpoint only)	For a keystore, create new keystore with a new name and an alias with the same name or with a new name. For a truststore, create a truststore with a new name.	Pass updated flow var on each request with the name of the new keystore, alias, or truststore. No Router or Message Processor restart is necessary.
Direct	Create a new keystore, alias, truststore.	Update the virtual host and restart the Routers. If the truststore is used by a target endpoint/target server, redeploy the proxy.
Direct	Delete the keystore or truststore and recreate it with same name.	No virtual host update required, no Router restart necessary. However, API requests fail until the new keystore and alias are set. If the keystore is used for two-way TLS between Edge and the backend service, restart the Message Processors.
Direct	For truststore only, upload a new cert to the truststore.	If the truststore is used by a virtual host, restart the Routers. If the truststore is used by a target endpoint/target server, restart the Message Processors.

Testing the cert before and after the update

Use the following openssl commands to test the current cert before you update it:

echo | openssl s_client -servername hostAlias -connect hostAlias.apigee.net:443 2>/dev/null | openssl x509 -noout -dates -subject

Where hostAlias the host alias of the virtual host or IP address. For example:

echo | openssl s_client -servername api.myCompany.com -connect api.myCompany.com:443 2>/dev/null | openssl x509 -noout -dates -subject

You should see output in the form:

notBefore=Dec 30 22:11:38 2015 GMT
notAfter=Dec 30 22:11:38 2016 GMT
subject= /OU=Domain Control Validated/CN=*.apigee.net

Use the same command after you update the cert to test it.

Update a TLS certificate in a keystore

For an on-premises deployment of Edge:

Create a new keystore and upload a cert and key as described at Keystores and Truststores. In the new keystore, ensure that you use the same name for the key alias as was used in the existing key store.

Note: You can delete the current keystore and create a new one with the same name and alias. No Router restart necessary. However, API requests fail until the new keystore and alias are set.
For a virtual host used by an inbound connections, meaning an API request into Edge:
1. If your virtual host uses a reference to the keystore, update the reference as described in Working with references.
2. If your virtual host uses a direct name of the keystore:
  1. Update any virtual hosts that referenced the old keystore and key alias to reference the new keystore and key alias.
  2. Restart the Routers, one at a time. Note that if you deleted the old keystore and created a new keystore with the same name, then no Router restart is necessary.
    
    No proxy redeployment required.
For a target endpoint/target server used by an outbound connections, meaning from Apigee to a backend server:
1. If the target endpoint/target server uses a references to the keystore, update the reference as described in Working with references. No proxy redeployment is necessary.
2. If the target endpoint/target server uses a flow variable, update the flow variable. No proxy redeployment is necessary.
3. If the target endpoint/target server uses a direct name of the keystore:
  1. Update the target endpoint/target server configuration for any API proxies that referenced the old keystore and key alias to reference the new keystore and key alias.
  2. For any API proxies that reference the keystore from a TargetEndpoint definition, you must redeploy the proxy.
    
    If the TargetEndpoint references a TargetServer definition, and the TargetServer definition references the keystore, then no proxy redeployment is necessary.
  3. If the keystore is used for two-way TLS between Edge and the backend service, and you deleted/recreated the keystore with the same name, you must restart the Edge Message Processors.
After you have confirmed that your new keystore is working correctly, delete the old keystore with the expired cert and key as described above.

Update a TLS certificate in a truststore

If you are using references to the truststore, the process of updating a cert in a truststore is the same as for a keystore as shown above. The only differences are:

When you upload the new cert to the new truststore the alias name does not matter for truststores.
If a cert is part of a chain, then you must either create a single file containing all the certs and upload that file to a single alias, or upload all certs in the chain separately to the truststore using a different alias for each cert.

If you are using direct names of your keystores and truststores:

Upload a new cert to the truststore as described in Keystores and Truststores. There is no need to delete the old cert.
For a virtual host used by an inbound connections, meaning an API request into Edge, restart the Routers one at a time.
For a target endpoint/target server used by an outbound connections, meaning from Apigee to a backend server, restart the Edge Message Processors one at a time.
Confirm that your new truststore is working correctly.