Template types
Templates provide modules to authenticate, apply threat protection to the APIs, and path-based routing and Service Callout policy to interact with the external endpoint for custom validation. A template is a combination of XML files. There are three proxy configuration templates provided by API Cloud v2.0.
To familiarize themselves with the publishing process, developers can use the sample templates to change configurations and become familiar with the policies. The following are included in this topic:
- Types of templates table
- Basic proxy template (AdvancedUser_APITemplate)
- Custom threat detection template (AdvancedUser_ThreatDetectionTemplate)
- Routing policy template (AdvancedUser_RoutingPolicyTemplate)
Types of templates
| Template Name | Description |
|---|---|
| AdvancedUser APITemplate (Basic Proxy Template) | |
| Enables CORS for the request | |
| Basic Threat detection. This enables threat detection with a predefined set limit and regex policies. Policy values cannot be edited. | |
| Note: If you want to customize threat detection policies, please use AdvanceUser_ThreatDetectionTemplate | |
| Authenticate with Trimble Identity | |
| Set Throttling | |
| AdvanceUser_ThreatDetectionTemplate(Custome Threate Detection Template) | |
| Enables CORS for the request | |
| Has three polices* jtp-limit,xml Defines limits for requests as JSON payload |
- xtp-limit.xml Defines limits for requests XML payload
- regextp.xml Defines regex patterns to detect any malicious content in the incoming payload such as SQL injection, XSS injection and so on.
For more information on how to configure the threat detection policies, see:* Authenticate with Trimble Identity
- Set Throttling
| | AdvanceUser_RoutingPolicyTemplate(Routing Policy Template) | Enable CORS for the request Basic Threat detection Authenticate with Trimble Identity Decode JWT once the request is successfully authenticated External Service callout to perform custom operations Path-based routing to the Target endpoints |
Basic proxy template (AdvancedUser_APITemplate)
You can perform the following configurations
Update Proxy Basepath and Target Endpoint through config
/proxy_config.json
<!-- add the base path for proxy -->"proxies":[ { "name":"default.xml", "tokens":[ { "xpath":"/ProxyEndpoint/HTTPProxyConnection/BasePath", "value":"/core/demoproxy/1.0" } ] }],
<!-- add the target endpoint -->"targets":[ { "name":"default.xml", "tokens":[ { "xpath":"/TargetEndpoint/HTTPTargetConnection/URL", "value":"http://mocktarget.apigee.net" } ] }]Update throttling values through config
/proxy_config.json{ "name":"SpikeArrest-ApiSpike.xml", "tokens":[ { "xpath":"/SpikeArrest/@enabled", "value":"true" }, { "xpath":"/SpikeArrest/Rate", "value":"10ps" <!-- possible values are ps|pm > } ]},{ "name":"Quota-ApiQuota.xml", "tokens":[ { "xpath":"/Quota/@enabled", "value":"true" }, { "xpath":"/Quota/Interval", "value":"10" }, { "xpath":"/Quota/TimeUnit", "value":"minute" <!-- possible values are minute, hour, day, week, or month. } ]}Enable Basic Threat Detection through config
/proxy_config.json
{ "name":"threat-protection.xml", "tokens":[ { "xpath":"/FlowCallout/@enabled", "value":"true" } ]}Custom threat detection Template (AdvanceUser_ThreatDetectionTemplate)
You can configure the following
Update Threat Detection Policies through config
proxy_config.json is placed at the root location where xml policies can be configured. The below snippet would have the configuration to update the threat detection limits and regex for the incoming request payload.
JSON limit customization
/proxy_config.json{ "name":"jtp-limit.xm", "tokens":[ { "xpath":"/JSONThreatProtection/@enabled", "value":"true" }, { "xpath":"/JSONThreatProtection/ArrayElementCount", "value":"100" }, { "xpath":"/JSONThreatProtection/ContainerDepth", "value":"50" }, { "xpath":"/JSONThreatProtection/ObjectEntryCount", "value":"30" }, { "xpath":"/JSONThreatProtection/ObjectEntryNameLength", "value":"20" }, { "xpath":"/JSONThreatProtection/StringValueLength", "value":"200" } ]}XML limit customization
/proxy_config.json{ "name":"xtp-limit.xml", "tokens":[ { "xpath": "/XMLThreatProtection/@enabled", "value": "true" }, { "xpath":"/XMLThreatProtection/NameLimits/Element", "value":"50" }, { "xpath":"/XMLThreatProtection/NameLimits/Attribute", "value":"20" }, { "xpath":"/XMLThreatProtection/NameLimits/NamespacePrefix", "value":"20" }, { "xpath":"/XMLThreatProtection/NameLimits/ProcessingInstructionTarget", "value":"150" }, { "xpath":"/XMLThreatProtection/StructureLimits/NodeDepth", "value":"25" }, { "xpath":"/XMLThreatProtection/StructureLimits/AttributeCountPerElement", "value":"10" }, { "xpath":"/XMLThreatProtection/StructureLimits/NamespaceCountPerElement", "value":"20" }, { "xpath":"/XMLThreatProtection/StructureLimits/ChildCount", "value":"20" }, { "xpath":"/XMLThreatProtection/ValueLimits/Text", "value":"200" }, { "xpath":"/XMLThreatProtection/ValueLimits/Attribute", "value":"200" }, { "xpath":"/XMLThreatProtection/ValueLimits/NamespaceURI", "value":"250" }, { "xpath":"/XMLThreatProtection/ValueLimits/Comment", "value":"100" }, { "xpath":"/XMLThreatProtection/ValueLimits/ProcessingInstructionData", "value":"150" } ]}Regex pattern customization
The regex pattern can be configured for the incoming request payload at the following levels.
-
URI Path
-
Headers
-
Query Params
-
Form Params
-
Request Payload
To configure regex pattern for incoming request URI path:
/apiproxy/policies/regextp.cml<!-- add URI Path tag --> <URIPath> <Pattern ignoreCase="false">pattern1</Pattern> <Pattern ignoreCase="false">pattern2</Pattern> <Pattern ignoreCase="false">pattern3</Pattern> </URIPath>Values for the above XML files will be provided via config file.
/proxy_config.json{ "name":"regextp.xml", "tokens":[ { "xpath":"/RegularExpressionProtection/@enabled", "value":"true" }, { "xpath":"/RegularExpressionProtection/URIPath/Pattern", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" }, { "xpath":"/RegularExpressionProtection/URIPath/Pattern[1]", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" }, { "xpath":"/RegularExpressionProtection/URIPath/Pattern[2]", "value":"<!--#(include|exec|echo|config|printenv)\\s+.*" } ]}Please verify the backward slash are propery escaped in the regex patterns if any exist.
To add the customized regex pattern, follow the steps to configure the rule in the template and config the values through config file.
apiproxy/policies/regextp.cml<!-- add Header tag --> <Header name="x-flag1"> <!-- define the pattern tag for the each regex | make ignoreCase attribute to true if you want regex to be case insensitive --> <Pattern ignoreCase="false">pattern1</Pattern> <Pattern ignoreCase="false">pattern2</Pattern> </Header> <Header name="x-flag2"> <Pattern ignoreCase="false">pattern1</Pattern> </Header>Values for the above XML files will be provided via config file.
/proxy_config.json{ "name":"regextp.xml", "tokens":[ { "xpath":"/RegularExpressionProtection/@enabled", "value":"true" }, { "xpath":"/RegularExpressionProtection/Header[@name='x-flag1']/Pattern", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" }, { "xpath":"/RegularExpressionProtection/Header[@name='x-flag2']/Pattern", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" } ]}One or more patterns can also be defined for the same Header tag
/proxy_config.json{ "name":"regextp.xml", "tokens":[ { "xpath":"/RegularExpressionProtection/@enabled", "value":"true" }, { "xpath":"/RegularExpressionProtection/Header[@name='x-flag1']/Pattern", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" }, { "xpath":"/RegularExpressionProtection/Header[@name='x-flag1']/Pattern[1]", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" } ]}The above configuration steps are same for Form and Query Params regex pattern customization.
How to configure regex pattern for incoming request Payload
/apiproxy/policies/regextp.cml<!-- add Variable tag and the name should be "request.content" which holds the incoming request payload on which the defined patterns will be applied --> <Variable name="request.content"> <Pattern ignoreCase="false">pattern1</Pattern> <Pattern ignoreCase="false">pattern2</Pattern> <Pattern ignoreCase="false">pattern3</Pattern> </Variable>Values for the above XML files will be provided via config file.
/proxy_config.json{ "name":"regextp.xml", "tokens":[ { "xpath":"/RegularExpressionProtection/@enabled", "value":"true" }, { "xpath":"/RegularExpressionProtection/Variable/Pattern", "value":"(.*)(\\b)+DELETE(\\b)+\/s.*(\\b)+FROM(\\b)+\/s.*(.*)" }, { "xpath":"/RegularExpressionProtection/Variable/Pattern[1]", "value":"<!--#(include|exec|echo|config|printenv)\\s+.*" } ]}Routing policy template (AdvanceUser_RoutingPolicyTemplate)
Update External endpoint through config
proxy_config.json is placed at the root location where xml policies can be configured. The below snippet would have the configuration to update the endpoint and http method of the Service callout.
"name": "external-callout.xml", "tokens": [ { "xpath": "/ServiceCallout/Request/Set/Verb", "value": "POST" }, { "xpath": "/ServiceCallout/HTTPTargetConnection/URL", "value": "https://mocktarget.apigee.net/echo" },Make Config on pathbased routing through config file
Based on the resource path, apigee able to route different target endpoints. In the sample proxy provided,
-
For the request path ‘/areas-test’ , routed to the target endpoint - ‘https://resourcetest.getsandbox.com:443’.
-
For the request path ‘/network-partners’, routed to the target endpoint - ‘https://mocktarget.getsandbox.com:443’. In order to add the new route, follow the below steps to configure the rule in the template and config the values through config file.
/apiproxy/proxies/default.xml<!-- add new route rule entry in the xml file. -- > <RouteRule name="default"> <Condition>request.verb == "POST"</Condition> <TargetEndpoint>default</TargetEndpoint> </RouteRule>
/apiproxy/targets/path-router2.xml<!-- Add new target xml file --><?xml version="1.0" encoding="UTF-8" standalone="yes"?><TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <Properties/> <URL>https://replaced_by_config_json</URL> </HTTPTargetConnection></TargetEndpoint>Values for the above XML files will be provided via config file
/proxy_config.json<!-- values to the route rule xml fields are pupulated using config file--> { "xpath": "/ProxyEndpoint/RouteRule[3]/@name", "value": "RouteRule2" }, { "xpath": "/ProxyEndpoint/RouteRule[3]/TargetEndpoint", "value": "networkPartnersService" }, { "xpath": "/ProxyEndpoint/RouteRule[3]/Condition", "value": "proxy.pathsuffix JavaRegex \"/network-partners/?.*\"" }
<!-- target xml are dynamically populated --> { "name": "path-router2.xml", "tokens": [ { "xpath": "/TargetEndpoint/@name", "value": "networkPartnersService" }, { "xpath": "/TargetEndpoint/HTTPTargetConnection/URL", "value": "https://mocktarget.getsandbox.com:443" } ] }RouteRule[3] represents order of the rule in the xml which needs to update the number based on the order.