The sample API JSON files shipped with API Security Enforcer (ASE) can be changed to your environment settings and are populated with default values.
The following table describes the JSON file parameters.
Parameter | Description | ||||||
---|---|---|---|---|---|---|---|
protocol |
API request type with supported values of:
|
||||||
url |
The value of the URL for the managed API. You can configure up to six levels of sub-paths. For example:
|
||||||
hostname |
Host name for the API. The value cannot be empty. “*” matches any host name. |
||||||
cookie |
Name of cookie used by the backend servers. |
||||||
cookie_idle_timeout |
The amount of time a cookie is valid, such as 20m for 20 minutes. The time duration formats include:
|
||||||
logout_api_enabled |
When true, ASE expires cookies when a logout request is sent. |
||||||
cookie_persistence_enabled |
When true, the subsequent request from a client is sent to the server which initially responded. |
||||||
oauth2_access_token |
When true, ASE captures OAuth2 Access Tokens. When false, ASE does not look for OAuth2 Tokens. Default value is false. For more information, see Capture client identifiers in inline mode. |
||||||
is_token_mandatory |
When set to true, if the request has a missing token, ASE adds the IP address of the client to deny list and blocks the request. When set to false, ASE does not block the client. Important:
For ASE to check and block the client the following values must be set to true:
The default value is false. |
||||||
apikey_qs |
When API Key is sent in the query string, ASE uses the specified parameter name to capture the API key value. For more information, see Capture client identifiers in inline mode. |
||||||
apikey_header |
When API Key is part of the header field, ASE uses the specified parameter name to capture the API key value. For more information, see Capture client identifiers in inline mode. |
||||||
login_url |
Public URL used by a client to connect to the application. |
||||||
enable_blocking |
When true, ASE blocks all types of attack on this API. When false, no attacks are blocked. Default value is false. |
||||||
api_memory_size |
Maximum ASE memory allocation for an API. The default value is 128 MB. The data unit can be MB or GB. |
||||||
health_check |
When true, enable health checking of backend servers. When false, no health checks are performed. Ping Identity recommends setting this parameter as true. |
||||||
health_check_interval |
The interval in seconds at which ASE sends a health check to determine backend server status. |
||||||
health_retry_count |
The number of times ASE queries the backend server status after not receiving a response. |
||||||
health_url |
The URL used by ASE to check backend server status. |
||||||
health_check_headers |
Configure one or more health check headers in the API JSON in a key-value format. This is an optional configuration and applies only to inline ASE deployment. In the sample JSON, the following example is provided:
The following table explains the sample JSON.
|
||||||
server_ssl |
When set to true, ASE connects to the backend API server over SSL. If set to false, ASE uses TCP to connect to the backend server. |
||||||
|
The IP address or hostname and port number of each backend server running the API. See REST API Protection from DoS and DDoS for information on optional flow control parameters. |
||||||
API Mapping: internal_url |
Internal URL is mapped to the public external URL See API Name Mapping – Protect Internal URLs for more information |
||||||
The following API Pattern Enforcement parameters only apply when API Firewall is activated |
|||||||
Flow Control client_spike_threshold server_connection_queueing bytes_in_threshold bytes_out_threshold |
ASE flow control ensures that backend API servers are protected from surges (for example DDoS, traffic spike) in API traffic. See WebSocket API Protection from DoS and DDoS for information on parameters. |
||||||
protocol_allowed |
List of accepted protocols Values can be HTTP, HTTPS, WS, WSS. Note:
When Firewall is enabled, protocol_allowed takes precedence over the protocol parameter. |
||||||
http_redirect response_code response_def https_url |
Redirect unencrypted HTTP requests to http_redirect, the FQDN address of a HTTPS secure connection. See Configuring Pattern Enforcement for details. |
||||||
methods_allowed |
List of accepted REST API methods. Possible values are:
|
||||||
content_type_allowed |
List of content types allowed. Multiple values cannot be listed. For example, application/json. |
||||||
error_code error_type error_message_body |
Error message generated by ASE after blocking a client. See ASE Detected Error Messages for details. |
||||||
|
When decoy_enabled is set to true, decoy sub-paths function as decoy APIs.
For more information see Configuring API deception for details. |
||||||
username_header |
The name of the custom header containing username. When the value of username_header is set, ASE extracts the username from the custom header. For more information, see Extract username from custom header in inline mode. Note:
You can configure username capture from either username_header or JWT object, but not both. |
||||||
|
When the parameter values of JWT object are set, ASE decodes the JWT to extract the user information.
For more information, see Extract user information from JWT in inline mode. Note:
You can configure username capture from either JWT object or username_header, but not both. |
The following is a sample JSON file for a REST API:
{
"api_metadata": {
"protocol": "http",
"url": "/rest",
"hostname": "*",
"cookie": "",
"cookie_idle_timeout": "200m",
"logout_api_enabled": false,
"cookie_persistence_enabled": false,
"oauth2_access_token": false,
"is_token_mandatory": false,
"apikey_qs": "",
"apikey_header": "",
"login_url": "",
"enable_blocking": true,
"api_mapping": {
"internal_url": ""
},
"api_pattern_enforcement": {
"protocol_allowed": "",
"http_redirect": {
"response_code": "",
"response_def": "",
"https_url": ""
},
"methods_allowed": [],
"content_type_allowed": "",
"error_code": "401",
"error_def": "Unauthorized",
"error_message_body": "401 Unauthorized"
},
"flow_control": {
"client_spike_threshold": "0/second",
"server_connection_queueing": false
},
"api_memory_size": "128mb",
"health_check": false,
"health_check_interval": 60,
"health_retry_count": 4,
"health_url": "/health",
"health_check_headers": {},
"server_ssl": false,
"servers": [
{
"host": "127.0.0.1",
"port": 8080,
"server_spike_threshold": "0/second",
"server_connection_quota": 0
},
{
"host": "127.0.0.1",
"port": 8081,
"server_spike_threshold": "0/second",
"server_connection_quota": 0
}
],
"decoy_config": {
"decoy_enabled": false,
"response_code": 200,
"response_def": "",
"response_message": "",
"decoy_subpaths": []
},
"username_header": "x-username-header",
"jwt": {
"location": "h:authorization:bearer",
"username": "username",
"clientid": "client_id"
}
}
}
Adding a configured API JSON file to ASE
Configure an API JSON file. For more information, see API JSON files configuration.
To add an API JSON file to ASE to activate ASE processing:
Updating a configured API
After activation, to update an API JSON definition in real time: