Send Docs Feedback

Update a TLS certificate

If a TLS certificate expires, or if your system configuration changes such that the certificate is no longer valid, then you need to update the certificate. The process of updating a certificate depends on your deployment of Edge: cloud or on-premises.

You cannot update an existing keystore to add a new certificate. You must create a new keystore when updating a certificate.

You can optionally choose to delete the existing keystore and then create a new one with the same name. However, for the time from when the certificate expired until you create the new keystore, you cannot service requests.


If the keystore is used for two-way TLS between Edge and the backend service, and you are using Edge for the Private Cloud, then after deleting and recreating the keystore with the same name, you must restart the Edge Message Processors.

If you configured the virtual host or the TargetEndpoint to use a reference to the keystore or truststore, you can update the reference to point to a different keystore or truststore to update the TLS cert. That means Cloud customers do not have to contact Apigee Support and Private Cloud customers do not need to restart a Router or Message Processor. However, Cloud customers must contact Apigee Support if they require an update to the virtual host. See Configuring TLS access to an API for the Private Cloud for more on using a reference in a virtual host or TargetEndpoint.

Determine when a cert is due to expire

Typically, you create a new keystore before the current certificate expires, and then update your virtual hosts or target endpoints to use the new keystore so that you can continue to service requests without interruption due to an expired certificate. You can then delete the old keystore after ensuring that the new keystore is working correctly.

To check when a certificate is due to expire, go to the Admin > SSL Certificates menu in the Edge management UI. You can also configure that page to indicate if a certificate is due to expire in 10, 15, 30, or 90 days. 

Update a TLS certificate in a keystore

The way you update a TLS certificate in a keystore is based on your Edge deployment type: cloud or Private Cloud.

Cloud deployment

For a cloud-based deployment of Edge:

  1. Create a new keystore as described in Keystores and Truststores.
  2. Upload a new JAR file containing the new certificate and private key to the keystore.
  3. For inbound connections, meaning an API request into Edge, contact Apigee Customer Support to update the virtual host configuration to reference the the new keystore and key alias.
  4. For outbound connections, meaning from Apigee to a backend server:
    1. Update the TargetEndpoint configuration for any API proxies that referenced the old keystore and key alias to reference the new keystore and key alias.

      If your TargetEndpoint references a TargetServer, update the TargetServer definition to reference the new keystore and key alias.
    2. If the keystore and truststore are referenced directly from the TargetEndpoint definition, then you must redeploy the proxy.

      If the TargetEndpoint references a TargetServer definition, and the TargetServer definition references the keystore and truststore, then no proxy redeployment is necessary.  
  5. After you have confirmed that your new keystore is working correctly, delete the old keystore with the expired cert and key as described above.

On-premises deployment

For an on-premises deployment of Edge:

  1. Create a new keystore as described in Keystores and Truststores.
  2. Upload a new JAR file containing the new certificate and private key to the keystore.
  3. For inbound connections, meaning an API request into Edge:
    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.
  4. For outbound connections, meaning from Apigee to a backend server:
    1. Update the TargetEndpoint configuration for any API proxies that referenced the old keystore and key alias to reference the new keystore and key alias.
      If your TargetEndpoint references a TargetServer, update the TargetServer definition to reference the new keystore and key alias.
    2. For any API proxies that reference the keystore and truststore from a TargetEndpoint definition, you must redeploy the proxy.

      If the TargetEndpoint references a TargetServer definition, and the TargetServer definition references the keystore and truststore, 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.
  5. 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

The way you update a TLS certificate in a truststore is based on your Edge deployment type: cloud or Private Cloud. 

Cloud deployment

For a cloud-based deployment of Edge:

  1. Upload a new cert to the truststore as described in Keystores and Truststores. There is no need to delete the old cert.
  2. For both inbound or outbound connections, contact Apigee Customer Support.
  3. Confirm that your updated truststore is working correctly.

On-premises deployment

For an on-premises deployment of Edge:

  1. Upload a new cert to the truststore as described in Keystores and Truststores. There is no need to delete the old cert.
  2. For inbound connections, meaning an API request into Edge, restart the Routers, one at a time. No proxy redeployment required.
  3. For outbound connections, meaning from Apigee to a backend server, restart the Edge Message Processors, one at a time.
  4. Confirm that your new truststore is working correctly.

Update your truststore for an expired Apigee cert

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.

Based on when you obtained your cert, the Apigee cert will expire on either February 23, 2016 or April 8, 2016. Apigee will be updating all keystores before those dates to upload a new cert and private key.

However, if you have uploaded the Apigee cert to a truststore, you must add the new Apigee cert to your truststore before it expires. You do not have to delete the old Apigee cert, you only have to upload the new one.

Shown below is the new cert:

-----BEGIN CERTIFICATE-----
MIIFHzCCBAegAwIBAgIISzef6agJ+w4wDQYJKoZIhvcNAQELBQAwgbQxCzAJBgNV
BAYTAlVTMRAwDgYDVQQIEwdBcml6b25hMRMwEQYDVQQHEwpTY290dHNkYWxlMRow
GAYDVQQKExFHb0RhZGR5LmNvbSwgSW5jLjEtMCsGA1UECxMkaHR0cDovL2NlcnRz
LmdvZGFkZHkuY29tL3JlcG9zaXRvcnkvMTMwMQYDVQQDEypHbyBEYWRkeSBTZWN1
cmUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5IC0gRzIwHhcNMTYwMTEzMTcyNTU0WhcN
MTkwNDA5MDYzNzEwWjA6MSEwHwYDVQQLExhEb21haW4gQ29udHJvbCBWYWxpZGF0
ZWQxFTATBgNVBAMMDCouYXBpZ2VlLm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEP
ADCCAQoCggEBALRAjJBUiGcKTEye40tpQjqGnAYn+LgpfS8Wkhh5nUZFvJBbEVDe
heH4Agc1LILOExEtKj/bGRhhFQzojSfTmz3LuGA8oVnzzOamYDvzkTkK5yO+Yd2C
FXgEOQhphcaZms2Z1Kl9cn1fQRl/+KUbiKgV/piu4079cnPqR8uME94mWnHpRurd
ZJqfOxpz+144RbTNaSJdQdiPQ1vzxmLQFFN2SrbWx4OXni/C5QJ0S14uplZHgw+j
Ae/LGAiaJR7nirot3QEk7qdYRF6g86OvrpToDbG6vKSyuIXoOT33oBJnjfFQRkq+
29VcMWwWLe6lmToGpp0xkNxdeyFB0oyQqFsCAwEAAaOCAawwggGoMAwGA1UdEwEB
/wQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMA4GA1UdDwEB/wQE
AwIFoDA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmdvZGFkZHkuY29tL2dk
aWcyczEtMTc4LmNybDBTBgNVHSAETDBKMEgGC2CGSAGG/W0BBxcBMDkwNwYIKwYB
BQUHAgEWK2h0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9y
eS8wdgYIKwYBBQUHAQEEajBoMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5nb2Rh
ZGR5LmNvbS8wQAYIKwYBBQUHMAKGNGh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRk
eS5jb20vcmVwb3NpdG9yeS9nZGlnMi5jcnQwHwYDVR0jBBgwFoAUQMK9J47MNIMw
ojPX+2yz8LQsgM4wIwYDVR0RBBwwGoIMKi5hcGlnZWUubmV0ggphcGlnZWUubmV0
MB0GA1UdDgQWBBROfmwEgDjmhQL41zDFmOsQ/Z/ARTANBgkqhkiG9w0BAQsFAAOC
AQEAq0MW3tOUPPdujGc2JLhd3SpYXCoHvps7JkjJ0yHurzXkCmnDHLAfYYXbu7Ei
B+k3anDavgGpO7odJQaoYtbpTCfZHRlUWSaT0Xef3UUIAMuu2bKIaNIYRTKUA7Jj
X4pCVTQCKHuoYMFjTAqm6d+q68WMv2oW6EERjf0irw++Yecuq+CllKIOird2zS73
Fc3RTp1LcM+J0AwHkA3r8KSCQhsqLdn/Y0JTxJ8d2E4RYH2jpkMB1ogA1/VUj9ZW
xTUVrk3Duw4Wq/66mPpQVGZHfRDJ9TBF5Qt8iUKxEIt4IzaWmk70049ygab29XaC
xaC2QIzKJJbBueo76nvKKpfeGQ==
-----END CERTIFICATE-----

Copy this cert to a PEM file, and then upload the certificate to your truststore. The way you update your truststore is based on its location and implementation. For example, if it is on your backend servers, use the procedure based on your server implementation.

If you are updating a truststore on Edge, use the Upload a Certificate to a Truststore API:

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

where the -F option specifies the path to the PEM file.

Help or comments?