Working with References

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

When configuring a TargetServer 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.

A reference can be represented by an XML object like the one below:

  <reference>
    <name>ReferenceName</name>
    <description>ReferencDescription</description>
    <resourceType>ReferredResourceType<resourceType>
    <refers>ReferredResource<refers>
  </reference>

The advantage to using a reference is that you can change the value of the reference to change the keystore used by the target server, usually because the cert in the current keystore is expiring in the near future.

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 on using references to keystores and truststore

If you have a load balancer and terminate TLS on the load balancer, then you cannot use keystore and truststore references in the target server.

Create a reference

You can use the Apigee UI or API to create a new reference.

Create in Apigee UI

To create a reference using the UI:

1. Log in to the Apigee UI.
2. Select the name of your organization.
3. Select Admin > Environments > References.
4. Select the Environment (typically prod or test).
5. Select the + Reference button.
6. In the Add Reference pop-up:
   1. Add the Name of the reference.
   2. Select the Reference, the referred keystore or truststore.
   3. Select Add Reference.

Create in Apigee API

To create a reference using the Create Reference API call:

      curl -H "Authorization: Bearer $TOKEN" \
        -X POST \
        -d '{
            "reference": {
              "name": MyReferenceName",
              "resourceType": "KeyStore",
              "refers": "KeyStoreID"
            }
           }' \
        https://apigee.googleapis.com/v1/{parent=organizations/*/environments/*}/references

Modify a reference

You can use the Apigee UI or API to modify an existing reference.

Modify in Apigee UI

To modify the value of a reference in the UI:

1. Log in to the Apigee UI.
2. Select the name of your organization.
3. Select Admin > Environments > References.
4. Select the Environment (typically prod or test).
5. Select the Edit button for the reference.
6. 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.
7. Save your updates.

Modify in Apigee API

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 -H "Authorization: Bearer $TOKEN" \
          -X PUT \
          -d '{
              "reference": {
              "name": MyReferenceName",
              "resourceType": "KeyStore",
              "refers": "KeyStoreID"
          }
         }' \
        https://apigee.googleapis.com/v1/{name=organizations/*/environments/*/references/*}