Working with references

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

When configuring a virtual host to support TLS, you specify a keystore or truststore by using a reference. A reference is a variable that contains the name of the keystore or truststore, rather than specifying the keystore or truststore name directly, as shown below:

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>

The advantage to using a reference is that you can change the value of the reference to change the keystore used by the virtual host, usually because the cert in the current keystore is expiring in the near future. Changing the value of the reference does not require you to restart the Edge Router.

You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore.

Restrictions in using references to keystores and truststore

You must take into account the following restriction when using references to keystores and truststores:

  • You can only use keystore and truststore references in virtual hosts if you support SNI and you terminate SSL on the Apigee Routers.
  • If you have a load balancer in front of the Apigee Routers, and you terminate TLS on the load balancer, then you cannot use keystore and truststore references in virtual hosts.

Creating a reference

To create a reference in the Edge UI:

  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. 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.
  4. Select the Environment (typically prod or test)
  5. Select the References tab.
  6. Select the + Reference button. The following pop-up appears:
  7. Specify the:
    1. Name of the reference.
    2. The entity referred to by the reference, meaning the keystore or truststore name.
    3. Select Save.

Alternatively, use the Create Reference API call to create the reference named keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u orgAdminEmail:password

The reference specifies the name of the keystore and its type. Use the same API call to create a reference to a truststore.

Modifying a reference

To modify the value of a reference in the Edge UI:

  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. 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.
  4. Select the Environment (typically prod or test)
  5. Select the References tab.
  6. In the Reference tab, select the Edit button for the reference.
  7. Update the reference to specify the new keystore or truststore. Caution: Ensure that the alias in the new keystore has the same name as the alias in the old keystore.
  8. Select Save.

To change the reference to point to a different keystore, ensuring that the alias in the new keystore has the same name as the alias in the old keystore, use the Update Reference API:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u orgAdminEmail:password