Setting up and configuring the Apigee proxy

Note

This topic is aimed at organization owners or administrators responsible for managing Apigee and the Developer portal set up and configuration.

Before users can start using Redocly's Developer portal with Apigee API, as an organization owner, you will need to set up an authorization proxy provided by Redocly in Apigee. This is a one-time setup only.

This proxy can:

  • authenticate users (verify IDP token),
  • create developers in Apigee,
  • allow access to routes needed only for managing developer applications and keys for a specific developer, and
  • forbid all other routes.

Why set up a proxy?

An API proxy is an additional layer or interface that developers use to access your organization's Apigee API. Setting up an API proxy allows you to separate the app-facing API from your backend services, shielding those apps from backend code changes.

You can also add capabilities such as security-related logging and monitoring and case-specific logic using the API proxy.

For more information, refer to Understanding APIs and API proxies.

This topic provides instructions on how to:

Prerequisites

  • For Apigee X you need to create a spcial service account in Google Cloud Console.

    Use the following tutorial: https://cloud.google.com/apigee/docs/hybrid/v1.2/sa-about Use Apigee Organization Admin permission and save a JSON key.

  • For Apigee Edge you need to create a service user account.

    Task 1: Upload proxy bundle to Apigee

Before you upload the proxy bundle to Apigee, you can download the proxy bundle from Redocly's private repo (include link). To get access to the proxy zip file, contact Redocly's customer support.

Note

Only authorized organization owners/developers will be given access to the private repo.

To upload the proxy bundle to your Apigee account:

  1. Log in to Apigee (Edge or X), and navigate to Develop > API Proxies.
  2. On the Proxies page, select +Proxy to display the Create proxy page. Add Proxy
  3. From the list of templates, select Upload proxy bundle. Create proxy list The Upload proxy bundle page displays.
  4. Drag and drop or click to upload the proxy bundle for your Apigee deployment type you would have downloaded from Redocly's private repository. The name field is automatically populated from the proxy bundle zip file. Upload proxy
  5. Select Next. The selected proxy bundle is uploaded and a Summary page displays.
  6. Select Create to upload the proxy bundle. A confirmation message displays and your proxy is uploaded successfully.

Task 2a): Set up key value map information for Apigee Edge

After uploading the proxy bundle, create key value maps and set up the system user credentials.

To create key value maps and set up user credentials:

  1. From Apigee Edge, navigate to Admin > Environments > Key Value Maps. The Key value maps page displays.
  2. Select +Key value map to display the Add key value map dialog. Add Key value map
  3. Enter a name for the key value map, select the Encrypted check-box. Added Key value map
  4. Select Add. A new key value map is created and displays on the key value maps list.
  5. Select to open the newly created key value map, and select + to add a key value pair. Add Key value pair
  6. For the selected key value map, add these key value pairs:

    • username: Enter the email address you use for accessing Apigee Edge.
    • password: Enter a password for the pair.

Task 2b): Set up key value map information for Apigee X

After uploading the proxy bundle, create key value maps and set up the service user credentials.

To create key value maps and set up user credentials:

  1. From Apigee X, navigate to Admin > Environments > Key Value Maps. The Key value maps page displays.
  2. Select +Key value map to display the Add key value map dialog. Add Key value map
  3. Enter a name for the key value map.
  4. Select Add. A new key value map is created and displays on the key value maps list.
  5. Set the contents of the service account JSON file (see prerequisites) as the serviceAccountCredentialsFile parameter of the KVM.
Note

You cannot add or retrieve data to the KVM in the Apigee X UI. You must use the KeyValueMapOperations policy to add or retrieve data to KVMs.

You can use https://github.com/apigee/devrel/tree/main/references/kvm-admin-api to set the values to the KVM. Follow the next steps to set the value using Redocly's built-in policy.

5.1. Navigate to Develop > API Proxies and select to open the API proxy you created in Task 1. 5.2. Select Develop tab, and:

  • Under Policies, select [example] Set Service Account Creds
  • Follow the instructions from the comment in the policy

Set Service Account creds via policy

Task 3: Map authentication credentials and deploy proxy

Once you have set up the key value map information, you can map the authentication credentials and deploy the proxy to the appropriate environment.

  1. Navigate to Develop > API Proxies and select to open the API proxy you created in Task 1.
  2. Select Develop tab, and:

    • Under Policies, select Get Auth Creds for Apigee Edge or Get Service Account Creds
    • Under Property Inspector, for mapIdentifier, enter system-user-creds (This is the key value map you created in Task 2) Map auth cred
  3. Select Save to save your changes.
  4. From the Deployment dropdown, select the environment you want to deploy the proxy to. A confirmation message displays. Deploy proxy
  5. Select Deploy. The proxy is now deployed to the selected environment and a deployment URL is generated for the proxy.
  6. Select Overview tab to view the deployment URL. Deploy URL
attention

You will need the deployment URL for connecting your Redocly Developer Portal to use your Apigee API.

Task 4: Configure Apigee proxy for IdP

In this step, organization owners add the JWKS URL from their OIDC provider into the Apigee proxy.

  1. In a browser, enter the Config URL. The browser displays a response in JSON format. Tip: You can find the Config URL in your OIDC setting. OIDC connect
  2. From the response body, copy the jwks_URL value. OIDC connect
  3. Navigate to Develop > API Proxies and select to open the API proxy you created in Task 1 and select the Develop tab.
  4. Under Policies, select Verify JWT. The Verify JWT code displays.
  5. Paste the jwks_URL into the code for JWKS uri. Verify JWT
  6. Select Save to save your changes.

Task 5: Add proxy details to Redocly's Developer portal and rebuild portal

After mapping the authentication credentials and deploying proxy to the appropriate environment, you will need to add proxy details to Redocly's Developer portal, to allow the portal to connect to the Apigee API.

To add proxy details in Redocly Worklows UI:

  1. In Redocly Workflows, navigate to your Developer portal settings.
  2. On the Settings page, select Environment variables to add two variables:

    • APIGEEORGNAME: Enter your Apigee organization name. Your Apigee organization name is displayed under your profile in Apigee. Apigee organization name
    • APIGEEPROXYURL: Enter the deployment URL you generated in Task 3.
    • APIGEE_VERSION: (optional) Version of Apigee deployment: apigeex (default) or apigeeedge. Add environment variables
  3. Navigate to the Overview tab, and select Rebuild to rebuild your developer portal using the new environment variables. Rebuild portal

    To add proxy details in portal source code:

  4. Navigate to your portal root folder and create a file named .env.production (or open it if it already exists).
  5. Configure APIGEEORGNAME and APIGEEPROXYURL the environment variables:
APIGEE_PROXY_URL=<Your deployment URL from Apigee>
APIGEE_ORG_NAME=<Your Apigee organization name>
APIGEE_VERSION=apigeex # or apigeeedge

All HTTP requests from your portal to Apigee API will now go through the Apigee proxy.