Product
Hosting Environment
Operating System
Capability
Task Type
Draft Beta
Close

PingIntelligence for APIs: Deployment Guide

Updated 61

Add to MyDocs | Hide Show Table of Contents

Add APIs to ASE

After installing ASE and ABS Engine, the next step is to add API definitions to the PingIntelligence for APIs software. This process can be completed automatically or manually.

Automatic API discovery

ABS AI Engine supports automatic discovery of APIs. The ABS Engine Admin Manual API Discovery section explains this process which operates as follows:

  • When traffic from an unknown API is passed to the ASE, it forwards the traffic metadata to the AI Engine which automatically discovers the API definition.
  • Ping Identity Automated API Definition (AAD) tool will then generate an API JSON file and load it to the ASE system.

After the API JSON definition is loaded, the AI Engine begins the training process. See the "Training" chapter in the ABS Admin Guide for more information on training the AI model.

Manual configuration of API definitions

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 ASE Admin Guide.

  1. Navigate to /opt/pingidentity/api_proxy/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 type: http - HTTP /REST API, ws - WebSocket
url

The value of the URL for the managed API. You can configure up to three 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

HTTP host header, for example, “api.xyz.com”

The value cannot be empty. “*” matches any hostname.

cookie Name of cookie used by backend servers.
oauth2_access_token When true, ASE captures OAuth2 Access Tokens.
apikey_qs When API Key is sent in the query string, ASE uses the specified parameter name to capture the API key value.
apikey_header When API Key is part of the header field, ASE uses the specified parameter name to capture the API key value.
login_url Public URL used by a client to connect to the application.
server_ssl When true, ASE uses SSL/TLS to secure backend connection. Default value is false.

Servers:

host

port

For each backend server running the API, configure:

  • Host - IP address or hostname
  • Port - the port number.

Flow Control:

client_spike_threshold

server_connection_queueing

bytes_in_threshold (WS)

bytes_out_threshold (WS)

ASE Flow Control ensures that backend API servers are protected from unplanned or malicious (for example, DDoS) surges in API traffic.
protocol_allowed Accepted protocols - HTTP, HTTPS, WS, or WSS.
methods_allowed Accepted methods. GET, POST, PUT, DELETE, HEAD
content_type_allowed Allowed content types allowed. For example, application/json

Decoy Config:

decoy_enabled

response_code

response_def

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

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

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 

Check the availability of access logs in ABS

Navigate to the data directory and check whether it has access logs sent by API Security Enforcer.

Enable attack blocking (optional)

ABS Engine generates a list of clients which executed attacks on an API service and can be configured to automatically send the attack list to ASE which blocks client access. By default, automatic blocking is inactive. Execute the following to activate automatic client blocking:

./cli.sh enable_abs_attack –u admin -p