Configurable proxy configuration examples

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

The ConfigurablePREVIEW 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.

Passthrough proxy

The simplest configuration model for a ConfigurablePREVIEW 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.

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 ConfigurablePREVIEW 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 ConfigurablePREVIEW 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