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.

Apigee in Google Cloud console

To create a reference using the Google Cloud console:

1. In the Google Cloud console, go to the Management > Environments page.

   Go to Environments

2. Select the desired environment where you want to create the reference.

3. Click the References tab.

4. Click Create Reference.

5. In the Create Reference pane, enter the following details:
   • Name: The name of the reference.
   • Keystore: The keystore to which the reference points.

6. Click Create.

Classic 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.

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.

Apigee in Google Cloud console

To modify a reference using the Google Cloud console:

1. In the Google Cloud console, go to the Management > Environments page.

   Go to Environments

2. Select the desired environment where you want to modify the reference.

3. Click the References tab.

4. In the displayed list, select the reference that you want to modify.

5. Click Actions > Edit.

6. In the Edit Reference pane, update the reference to specify the new keystore.

7. Click Update.

Classic 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.

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 '{
              "name": "MyReferenceName",
              "resourceType": "KeyStore",
              "refers": "KeyStoreID"
              }' \
        https://apigee.googleapis.com/v1/{name=organizations/*/environments/*/references/*}