Configurable proxy configuration examples

You're viewing Apigee X documentation.
View Apigee Edge documentation.

Preview — Configurable API Proxies

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Support for the Preview launch of Configurable API Proxies is available through the Apigee - Google Cloud Community forum.

The Configurable^PREVIEW API proxy schema provides a number of options for adding features to your proxy. The following sections provide examples of proxy configurations used to support common use cases. More detailed information regarding configuration options is available on the ApiConfig schema reference page. The ApiConfig schema is used to structure the YAML file that defines a configurable proxy.

Note: Each example below uses mocktarget.apigee.net as the backend service purely for illustration purposes. This target should be replaced with your own backend when testing your configuration.

Passthrough proxy

The simplest configuration model for a Configurable^PREVIEW API proxy is the passthrough proxy configuration. In this configuration, the proxy receives traffic on a basePath and routes the information to a backend target.

For example:

#proxy.yaml
basepath: "/helloworld"

target:
  uri: https://mocktarget.apigee.net

In this example, the first line of the configuration contains the base path. This is a mandatory parameter.

The rules section of the configuration contains the target endpoint for routing all incoming requests. This proxy bundle example does not apply security or routing information for additional endpoints.

Note: The above configuration is for illustration purposes only. Proxies that do not contain operations will return a 404 error code. For more information, see Apigee known issues.

Proxy with operations

In this example, the configuration declares operations (or method/path combinations) so that an API proxy developer can implement different actions, or enforce different policies, based on the operation requested.

For example:

#proxy.yaml
basepath: "/helloworld"

target:
  uri: https://mocktarget.apigee.net

operations:  # First match wins
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*" # A single "*" matches a single path segment
    method: GET

In this example, the operations section of the configuration functions in a manner similar to flow conditions in a programmable proxy bundle. For more information on how flow conditions are used, see Having code execute conditionally with a conditional flow.

Proxy with Security enforcement

An important part of API security involves controlling access to your APIs, accessing and masking sensitive encrypted data at runtime, and protecting your backend services against direct access. With Configurable^PREVIEW API proxies, several security enforcement options can be implemented, as detailed in the following examples.

Enable API key verification

In this example, the configuration enables API key verification for all exposed operations. The rule to enforce API key verification is known as consumer_authorization. This configuration rule checks for the presence of an API key is a given location. If a key is present, the rule checks the validity of the API key and whether the API key has access to the API (i.e., if the API key has subscribed to an API product with access the API proxy).

For example:

#proxy.yaml
basepath: "/helloworld"

operations:
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*"
    method: GET

target:
  uri: https://mocktarget.apigee.net

consumer_authorization:  # API Key enforcement
  locations:
  - header: x-api-key

Becuse the consumer_authorization rule is located the global section of the proxy, the rule applies to all operations in the proxy bundle.

Enable OAuth

There are two aspects to enabling OAuth for Configurable^PREVIEW API proxies:

• Obtaining an OAuth access token
• Validating/Granting access to APIs

Each aspect is described in the following sections.

Obtain an OAuth Access Token

The process of obtaining OAuth access tokens for a configurable proxy is the same as for a programmable proxy. OAuth access tokens are obtained using programmable API proxy bundles. For examples of the steps required to configure an the OAuth2 policy, see Requesting access tokens and authorization codes.

Validate and authorize access to APIs

The following steps are required to validate and authorize OAuth access tokens with Apigee:

1. Define the JWT authentication requirement. This section defines how the proxy validates a JWT token.

   For example:

   #proxy.yaml
   authentication:
     jwt:
       id: apigee_oauth
       audiences: ["developer-app1"]
       issuer: "SERVICE_ACCOUNT_EMAIL"
       remote_jwks:
         uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
         cache_duration: 600s
       locations:
       - header: Authorization
         transformation:
           template: "Bearer {token}"
           substitution: "{token}"
   
   target:
     uri: https://mocktarget.apigee.net
   
   consumer_authorization:
     locations:
     - jwt_claim:
         requirement: apigee_oauth
         name: client_id

2. Define the location of the Apigee client ID used to access the API. This is typically a JWT claim containing the credential Apigee uses to authorize access to API products by developer applications.

   For example:

   #proxy.yaml
   authentication:
     jwt:
       id: apigee_oauth
       audiences: ["developer-app1"]
       issuer: "SERVICE_ACCOUNT_EMAIL"
       remote_jwks:
         uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
         cache_duration: 600s
       locations:
       - header: Authorization
         transformation:
           template: "Bearer {token}"
           substitution: "{token}"
   
   target:
     uri: https://mocktarget.apigee.net
   
   consumer_authorization:
     locations:
     - jwt_claim:
         requirement: apigee_oauth
         name: client_id

The combined configuration to validate and authorize API access would appear as follows:

#proxy.yaml
authentication:
  jwt:
      id: apigee_oauth
      audiences: ["developer-app1"]
      issuer: "SERVICE_ACCOUNT_EMAIL"
      remote_jwks:
        uri: "https://www.googleapis.com/service_accounts/v1/jwk/serviceaccount"
        cache_duration: 600s
      locations:
      - header: Authorization
        transformation:
          template: "Bearer {token}"
          substitution: "{token}"


target:
  uri: https://mocktarget.apigee.net

consumer_authorization:
  locations:
  - jwt_claim:
      requirement: apigee_oauth
      name: client_id

This proxy configuration ensures that all requests to the target endpoint contain the following:

• A JWT that meets the following criteria:
  • Has a matching issuer and audiences
  • Is verified by the contents of the JWKS URI
  • Is present in the Authorization header
• Client credentials are within the matching apigee_oauth JWT's claim client_id

Enable CORS

In this example, the proxy configuration defines rules for enabling CORS. CORS (Cross-origin resource sharing) is a standard mechanism that allows JavaScript XMLHttpRequest (XHR) calls executed in a web page to interact with resources from non-origin domains. CORS is a commonly implemented solution to the same-origin policy that is enforced by all browsers.

For example:

#proxy.yaml
basepath: "/helloworld"

cors:
  allow_origins:
  - "*"
  allow_methods:
  - "GET"
  allow_headers:
  - "Accept"
  max_age: 600
  allow_credentials: false

operations:
- id: help
  http_match:
  - path_template: "/help"
    method: GET
- id: status
  http_match:
  - path_template: "/status/*"
    method: GET

target:
  uri: https://mocktarget.apigee.net

Using Target Servers

The configurable proxy model supports the Apigee concept of target servers. Using target servers allows you to decouple your concrete endpoints from your target endpoints to support load balancing and failover across multiple backend server instances. To use target servers in an archive deployment, use the following examples for your proxy.yaml and targetservers.json files:

#proxy.yaml
basepath: "/mock"

operations:
- id: user
  http_match:
  - path_template: "/user"
    method: "GET"

target:
  target_server_id: mocktarget

In the targetservers.json file:

[
    {
        "name": "mocktarget",
        "host": "mocktarget.apigee.net",
        "port": 443,
        "isEnabled" : true,
        "sSLInfo": {
            "enabled": true
        }
    }
]

Route Operations to Targets

In this example, the configuration proxy model enables users to route each operation to a different target endpoint.

For example:

#proxy.yaml
basepath: "/mockhttpbin"

operations:
- id: user
  http_match:
  - path_template: "/user"
    method: "GET"
  target:
    target_server_id: mocktarget
- id: ip
  http_match:
  - path_template: "/ip"
    method: "GET"
  target:
    uri: https://httpbin.org