Update a TLS certificate for the 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.

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 HOSTNAME -connect ORG-ENV.apigee.net:443 2>/dev/null | openssl x509 -noout -dates -subject

where HOSTNAME is the host alias and ORG-ENV is the organization and environment. For example:

echo | openssl s_client -servername example.com -connect myOrg-prod.apigee.net: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.

Determine how you virtual host or target endpoint/target server references the keystore and truststore

1. Login to the Edge management UI at https://enterprise.apigee.com.
2. In the Edge management UI menu, select the name of your organization.
3. For a virtual host, determine how the virtual host specifies the keystore and truststore.
   1. Depending on your version of the Edge UI:
      1. If you are using the Classic Edge UI: Select APIs > Environment Configuration.
      2. If you are using the New Edge UI: Select Admin > Environments.
   2. Select the Virtual Hosts tab.
   3. For the specific virtual host that you are updating, select the Show button to display its properties. The display includes the following properties:
      1. Key Store: The name of the current keystore, typically specified as a reference in the from ref://mykeystoreref.
         
         Alternatively, it might be specified by a direct name, in the form myKeystoreName, or it might be specified by a flow variable, in the form {ssl.keystore}.
      2. Key Alias. The value of this property is the alias name in the keystore. Your new keystore must create an alias with the same name.
      3. Trust Store: The name of the current truststore, if any, typically specified as a reference in the from ref://mytruststoreref.
         
         Alternatively, it might be specified by a direct name, in the form myTruststoreName, or it might be specified by a flow variable, in the form {ssl.truststorestore}.
4. For a target endpoint/target server, determine how the target endpoint specifies the keystore and truststore:
   1. In the Edge management UI menu, select APIs.
   2. Select the name of the API proxy.
   3. Select the Development tab.
   4. Under Target Endpoints, select default.
   5. In the code area, the TargetEndpoint definition appears. Examine the <SSLInfo> element to see how the keystore/truststore is defined.
      
      Note: If the target endpoint uses a target server, then the XML definition of the target endpoint appears as below, where the <LoadBalancer> tag specifies the target servers used by the API proxy.

      <TargetEndpoint name="default">
        …
        <HTTPTargetConnection>
          <LoadBalancer>
            <Server name="target1" />
            <Server name="target2" />
          </LoadBalancer>
          <Path>/test</Path>
        </HTTPTargetConnection>
          …
      </TargetEndpoint>

      Examine the <SSLInfo> element in the target server definition to determine how the keystore/truststore is defined.

Update a TLS certificate in a keystore

When a cert in a keystore expires, you cannot upload a new cert to the keystore. Instead, you create a new keystore and upload the cert, then update your virtual hosts or target server/target endpoint to use the new keystore.

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.

For a Cloud-based deployment of Edge:

1. Create a new keystore and upload a cert and key as described in Creating keystores and truststore using the Edge UI.

   In the new keystore, ensure that you use the same name for the key alias as was used in the existing key store.

2. For a virtual host used by an inbound connection, meaning an API request into Edge:
   1. If your virtual host uses a reference to the keystore, update the reference.
   2. If your virtual host uses a direct name of the keystore, contact Apigee Edge Support.
3. For a target endpoint/target server used by an outbound connection, meaning from Apigee to a backend server:
   1. If the target endpoint/target server uses a references to the keystore, update the reference. 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, 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.

      You must then redeploy the proxy.

4. After you have confirmed that your new keystore is working correctly, delete the old keystore with the expired cert and key.

Update a TLS certificate in a truststore

When a cert in a truststore expires, you typically create a new truststore and upload the cert, then update your virtual hosts or target server/target endpoint to use the new truststore.

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.

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

For a Cloud-based deployment of Edge:

1. Create a new truststore and upload a cert as described in Creating keystores and truststore using the Edge UI.

   When you upload the new cert to the new truststore the alias name does not matter.

2. For a virtual host used by an inbound connection, meaning an API request into Edge:
   1. If your virtual host uses a reference to the truststore, update the reference.
   2. If your virtual host uses a direct name of the truststore, contact Apigee Edge Support.
3. For a target endpoint/target server used by an outbound connection, meaning from Apigee to a backend server:
   1. If the target endpoint/target server uses a references to the truststore, update the reference. 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 truststore, update the target endpoint/target server configuration for any API proxies that referenced the old truststore to reference the new keystore and key alias.

      You must then redeploy the proxy.

4. After you have confirmed that your new truststore is working correctly, delete the old truststore with the expired cert.