Protecting APIs on Apigee X Gateway

Learn how to discover, integrate and protect your APIs deployed behind the Apigee X Gateway. In this article, you will create an Apigee X Authorizer in ACP, integrate it with ACP, and configure your Apigee X Gateway.

Prerequisites

  • Docker and Docker Compose

  • Access to an ACP tenant

  • Apigee X account with an active organization

  • Google Cloud Platform (GCP) access

  • An organization added to GCP

  • Privileges necessary to get an authentication key in GCP’s Services Accounts

Create Apigee X gateway

  1. Log in to your ACP tenant.

  2. Open your authorization server (workspace).

  3. Go to APIs -> Gateways.

  4. Select Add Gateway. A list of available gateways appears.

  5. Select Apigee X. Provide the name and description.

  6. Optionally, enable the Create and bind services automatically check box.

    Tip

    When enabled, all services protected by your Apigee X instance are discovered and added to the ACP service list automatically when the Apigee authorizer is connected to ACP. Otherwise, you need to add them manually.

  7. Download the authorizer’s package from the Quickstart instruction.

Integrate ACP and Apigee X Authorizer

  1. In GCP service accounts for your project, create a new key that you will use for authenticating your authorizer to your Google Cloud organization.

    Note

    The key should be in the JSON format.

  2. Unzip the package and open the docker-compose.yaml file.

  3. Move the key that you have created in the first step to your authorizer’s directory.

  4. Edit the docker-compose.yaml file for your authorizer.

    Tip

    The APIGEE.ACP_RELOAD_INTERVAL configuration parameter defines how often ACP tries to discover APIs on your gateway.

    Add the GOOGLE_APPLICATION_CREDENTIALS environment variable under the environment node. The value of your variable should be a path to the JSON file that contains the authentication key from GCP.

    Example

    environment:
    - APIGEE.APIGEE_PRODUCT=ApigeeX
    - APIGEE.ACP_RELOAD_INTERVAL=5s # for demo purposes only, increase for production!
    - GOOGLE_APPLICATION_CREDENTIALS=/apigee/apigee-integration-sample.json
    - SHARED_FLOW_PATH=/data/data
    

    Add a volumes parameter.

    Example

    volumes:
    - /Path/To/Your/Authorizer/apigee-x-authorizer:/apigee
    

    volumes attaches the defined catalog (/Path/To/Your/Authorizer/apigee-x-authorizer) to your authorizer’s docker image and maps it to a catalog that, from now on, exists on your docker image (apigee). This is the place where your Google Application credentials are stored on your authorizer’s docker deployment.

    Save the docker-compose.yaml file once you are done with your changes.

  5. Run the docker-compose run apigee-authorizer install command in your terminal.

    Result

    When you run the command, a shared Authorizer flow is created automatically for you in your Apigee X instance. The shared flow consists of two policies:

    • A JavaScript Cloudentity Authorizer Policy that is responsible for communicating with the Apigee X Authorizer and for blocking/allowing the request depending on the Authorizers decision.

    • An XML Raise Authorization Error policy that is responsible for delivering the error status as the response to the unauthorized call to the protected API.

  6. Run docker-compose up. After a short while, Apigee X authorizer should be running.

    docker-compose up
    Starting apigee-x-authorizer ... done
    Attaching to apigee-x-authorizer
    apigee-x-authorizer  | time="2021-09-28T13:55:28Z" level=info msg="starting apigee authorizer" commit=b132c7c version=1.13.0
    apigee-x-authorizer  | time="2021-09-28T13:55:29Z" level=info msg="apigee-authorizer listening on https://localhost:8442"
    apigee-x-authorizer  | time="2021-09-28T13:55:34Z" level=info msg="Starting authorizer reload..."
    apigee-x-authorizer  | time="2021-09-28T13:55:36Z" level=info msg="Authorization configuration reloaded (1.0898772s)"
    
  7. Go to APIs > Gateways > your_gateway > APIs. You should see a familiar list of services deployed using Apigee X.

    Note

    If you do not see a list of services deployed on Apigee X, make sure that at least one API Product is defined in your Apigee X organization with a connected API proxy.

    Note

    If you need to limit the count of discovered APIs, you can configure product_name_regexp or environment_name_regexp. Setting it up will limit discovered APIs to matching names.

  8. Select Connect > Create new service on a protected API from the list to add it to the list of ACP-protected services. Give this new ACP service a name when prompted.

    Note

    If you selected the Create and bind services automatically option when creating the gateway, your services are bound already.

    Result

    Your Apigee X-protected API is now on the list of ACP-protected services.

  9. Deploy your Apigee X authorizer so that it is available publicly.

    Tip

    So far, you have only deployed your Apigee X authorizer locally using the Docker image provided by Cloudentity. You must expose it publicly as it is needed later on for the integration to work. For testing purposes, you can use tools like, for example, ngrok that expose local servers behind NATs and firewalls to public internet over secure channels.

Configure Apigee X Gateway

With Apigee X Gateway, you can define policies that are Apigee X components that you can attach to different points in the message flow through your API proxies. Such policies can transform the message format, call remote services, and more. To protect your APIs, elevate the integration between ACP and the Apigee X platform. Doing so allows you to enforce access control using Apigee X policies and ACP authorization policies.

  1. In your Apigee X Proxy settings, go to the DEVELOP tab.

  2. In the Navigator > Policies add a policy of the Flow Callout type.

    Tip

    You can find the Flow Callout policy type under the EXTENSTION tree node.

  3. Provide a name and a display name for your policy.

  4. As a shared flow, use the Authorizer shared flow.

    Result

    Your policy is created. It is defined with the following XML:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout">
      <DisplayName>Flow Callout</DisplayName>
      <FaultRules/>
      <Properties/>
      <SharedFlowBundle>Authorizer</SharedFlowBundle>
    </FlowCallout>
    
  5. Configure your policy so that it points to your Apigee X authorizer’s /authorize endpoint that you have deployed in the seventh step of the Integrate ACP and Apigee X section

    Example

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <FlowCallout async="false" continueOnError="false" enabled="true" name="microPerimeter">
       <DisplayName>microPerimeter</DisplayName>
       <FaultRules/>
       <Properties/>
       <Parameters>
           <Parameter name="authorizer_url">https://yourAuthorizerURL/authorize</Parameter>
           <Parameter name="proxy_body">false</Parameter>
       </Parameters>
       <SharedFlowBundle>Authorizer</SharedFlowBundle>
    </FlowCallout>
    

    proxy_body parameter

    If the proxy_body parameter is set to true, the shared flow policy proxies the request body to the authorizer and then to the policies. Thanks to that it is possible to create policies that reject requests based on the request body. The request body must be in the JSON format.

    The proxy_body option is disabled by default to make it possible to use bigger-sized request bodies, for example, for image uploads.

  6. Add your new policy as a <step> element to your Proxy Endpoints PreFlows.

    Example

    <PreFlow name="PreFlow">
       <Request>
           <Step>
               <Name>microPerimeter</Name>
           </Step>
       </Request>
       <Response/>
    </PreFlow>
    

    Note

    You have to add your new policy to your Proxy Endpoints PreFlows, as the authorization must take place before the request reaches to target endpoint.

  7. Select Save.

Apply a sample policy

  1. In ACP, create a policy.

  2. Select APIs from the left sidebar and go to the AUTHORIZATION tab.

  3. Select a service protected by the Apigee X authorizer and any API with authorization status Unrestricted.

  4. In the Edit API popup window, select Policy from the dropdown list and click Update to proceed.

Result

You have successfully assigned a policy to your API.

Test integration

To test if your integration was successfull and that your APIs are protected, you can, for example, create a simple Cloudentity or REGO policy that will always pass. Call your protected endpoint and check if the response contains the successfull status. If yes, change your policy so that it blocks APIs. The next request to your protected enpoint should end with the unauthorized access error.