Defining an API using API JSON configuration file in inline mode

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.

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 next table explains the sample JSON.

server_ssl

When set to true, ASE connects to the backend API server over Secure Sockets Layer (SSL). If set to false, ASE uses TCP to connect to the backend server.

Servers:

host port server_spike_threshold server_connection_quota

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.

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.

Decoy Config

decoy_enabled response_code response_def response_message decoy_subpaths

When decoy_enabled is set to true, decoy sub-paths function as decoy APIs.

response_code

The status code (for example, 200) that ASE returns when a decoy API path is accessed.

response_def

The response definition (for example OK) that ASE returns when a decoy API path is accessed.

response_message

The response message (for example OK) that ASE returns when a decoy API path is accessed.

decoy_subpaths

The list of decoy API sub-paths (for example shop/admin, shop/root).

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.

JWT

location username clientid

When the parameter values of JWT object are set, ASE decodes the JWT to extract the user information.

location

The place of occurrence of JWT in an API request. The supported values are:

username

The JWT claim to extract the username.

clientid

The JWT claim to extract the client-id

For more information, see Extract user information from JWT in inline mode.

X-Host

%{HOST} - If your backend server requires the value of header to contain host name or IP address of the server, use %{HOST} in value. During health check, ASE dynamically replaces header values containing %{HOST} with host name or IP address of the server.

In the sample API JSON, ASE will dynamically replace %{HOST} with IP address (127.0.0.1) configured in the servers section.

X-Custom-Header

Your custom header value. All the custom health check headers configured are sent to all the backend API servers.