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:
#config.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:
#config.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 in 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 to the API proxy).
For example:
#config.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
Because 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:
- Define the JWT authentication requirement. This section defines how the proxy validates a JWT token.
For example:
#config.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
- 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:
#config.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:
#config.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
andaudiences
- Is verified by the contents of the JWKS URI
- Is present in the
Authorization
header
- Has a matching
- Client credentials are within the matching
apigee_oauth
JWT's claimclient_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:
#config.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 config.yaml
and
targetservers.json
files:
#config.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:
#config.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