Attention:

Configure API discovery when API Security Enforcer (ASE) is deployed in sideband mode. To configure ASE for inline discovery, contact Ping Identity support.

ASE requires a root definition that enables it to route all API traffic to the AI engine. The AI engine receives and monitors all API traffic that is not associated with a known API. It analyzes the traffic and builds API models for the unknown APIs, which are shown on the Discovery dashboard.

To add a root API in ASE:

  1. Use the sample root API JSON shipped with ASE in the <ASE_Installation path>/pingidentity/ase/config/api/ directory and configure the API JSON for the root API.

    For sideband environments, use the following settings:

    Parameter Setting

    protocol

    http

    url

    /

    hostname

    *
  2. To capture client identifiers such as token, cookies, API keys, IP addresses, and username, configure the root API JSON file with the following client identifiers.
    Note:

    If the identifiers are not present in at least 50% of the traffic received for a discovered API, then the identifiers are not reported or used in Indicator of Attack (IoA) detection.

    Client Identifier Description

    oauth2_access_token

    If a bearer token is present, set to true.

    cookie

    If cookies are used as the primary client identifier, configure the cookie name.

    apikey_qs or apikey_header

    Set for the API key in query parameter or for the API key in header.

    The following is a sample API JSON for the root API:

    
{
 "api_metadata": {
 "protocol": "http",
 "url": "/",
 "hostname": "*",
 "cookie": "",
 "oauth2_access_token": true,
 "apikey_qs": "",
 "apikey_header": "",
 "login_url": "",
 "enable_blocking": true,
 "api_memory_size": "1mb",
 "decoy_config":
{ "decoy_enabled": false, "response_code": 200, "response_def": "", "response_message": "", "decoy_subpaths": [] }
}
 }
    Note:

    IP addresses and usernames are captured separately.

  3. After configuring an API JSON file for the root API, add it to ASE to initiate the API discovery process by running the following command: 
    /<ASE_Installation path>/pingidentity/ase/bin/cli.sh –u admin -p admin add_api {file_path/api_name}