To secure an API with PingIntelligence for APIs software, an administrator can add an API definition to the Ping Identity ASE, which will then pass the API information to the AI Engine for reporting and attack detection. Complete the following steps to configure a simple REST API. For more information on advanced options, see the ASE Admin Guide.

  1. Navigate to /opt/pingidentity/ase/config/api and copy the file rest_api.json.example to rest_api.json
  2. Open the rest_api.json file and update the following information:
    1. Update the “url” to the base path of the API, for example, “/apiname”
    2. Replace the server IP addresses and ports with the addresser/ports of your app servers.
    3. Review the following parameter list and make other edits as applicable.

Key API JSON file parameters to configure include:

Parameter Description
protocol

API request type with supported values of:

ws - WebSocket ; http - HTTP
url

The value of the URL for the managed API. You can configure up to six levels of sub-paths. For example,

"/shopping"- name of a 1 level API

"/shopping/electronics/phones" – 3 level API

"/" – entire server (used for ABS API Discovery or load balancing)
hostname

Hostname for the API. The value cannot be empty.

“*” matches any hostname.
cookie

Name of cookie used by the backend servers.
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-inline and Capture client identifiers - Sideband.
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-inline and Capture client identifiers - Sideband.
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-inline and Capture client identifiers - Sideband.
login_url Public URL used by a client to connect to the application.
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.
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.

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.

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.
methods_allowed

List of accepted REST API methods. Possible values are:

GET, POST, PUT, DELETE, HEAD

content_type_allowed List of content types allowed. Multiple values cannot be listed. For example, application/json.

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 is the status code (for example, 200) that ASE returns when a decoy API path is accessed.

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

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

decoy_subpaths is the list of decoy API sub-paths (for example shop/admin, shop/root)

See API deception for details

After configuring the API JSON file, add it to ASE for it to take effect. To add a runtime API, execute the following CLI command:

/opt/pingidentity/ase/bin/cli.sh add_api {file_path/api_name} –u admin -p

Verify/List the API

To verify whether the API that you added has been successfully added or not, run the list API command:

opt/pingidentity/ase/bin/cli.sh list_api -u admin -p