PingIntelligence

Extract username from custom header in inline mode

This topic discusses the extraction of a username from a custom header when API Security Enforcer (ASE) is in inline mode.

ASE supports capturing usernames from custom headers in a request. It extracts the username and logs it in ASE access logs. ASE sends these access log files to API Behavioral Security (ABS) AI Engine to detect attacks. The following is an example of username information logged in the ASE access log:

[Tue Dec 15 09:13:45:044 2020] [thread:999] [info] [connectionid:1801979802] [connectinfo:127.0.0.0:80] [type:connection] connection received
[Tue Dec 15 09:13:45:044 2020] [thread:999] [info] [connectionid:1801979802] [seq:1] [connectinfo:127.0.0.0:80] [type:request] [api_id:api1] GET /abcd HTTP/1.1
x-username-header: 12n4uf9ckls

host: http://pi-api-mngmnt.azr-api.net/
accept: /
content-type: text/plain;charset=UTF-8

[Tue Dec 15 09:13:45:044 2020] [thread:999] [info] [connectionid:1801979802] [seq:1] [connectinfo:127.0.0.0:80] [type:backend_info] [backend_type:nonssl] [0] [api_id:api1] [hostname:not available] backend selected
[Tue Dec 15 09:13:45:044 2020] [thread:999] [info] [connectionid:1801979802] [seq:1] [connectinfo:127.0.0.0:80] [type:req_payload] [api_id:api1] [size:0]
[Tue Dec 15 09:13:45:044 2020] [thread:999] [info] [connectionid:1801979802] [seq:1] [connectinfo:127.0.0.0:80] [type:user_info] [api_id:api1] username: 12n4uf9ckls

The following diagram shows the traffic flow when ASE is in inline mode.

Diagram of traffic flow when ASE is in inline mode

When deployed in inline mode, ASE extracts the username from either JSON Web Token (JWT) or a custom header. It checks the configuration of application programming interface (API) JavaScript Object Notation (JSON) file. It first checks the JWT object. If it is configured, then ASE will capture the username from a JWT in the incoming request. Otherwise, ASE checks the username_header parameter in API JSON. If it is set, ASE extracts the username from the custom header that comes as part of an incoming request. For more information, see the Configure API JSON section below.

Flowchart for processing username in inline mode

ASE supports extracting username from either JWTs or a custom headers. You can configure API JSON to capture username from either custom header or JWT, but not both for a given API. For more information on extracting usernames from JWTs, see Extract user information from JWT in inline mode.

API JSON configuration in inline mode

The behavior and properties of your API are defined in an API JSON file in the ASE. To enable username capture from a custom header, set the value of the username_header parameter to the custom header name containing the username. The following is an example of an API JSON file.

{
  "api_metadata": {
    "protocol": "http",
    "url": "/rest",
    "hostname": "*",
    "cookie": "",
    "cookie_idle_timeout": "200m",
    "logout_api_enabled": false,
    "cookie_persistence_enabled": false,
    "oauth2_access_token": 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": "",
      "username": "",
      "clientid": ""
    }
  }
}

For more information, see Defining an API using API JSON configuration file in inline mode.

You can optionally block a client. When enable_blocking is set to true, ASE checks the username against the list of usernames in the allow list and deny list. If the username is in the deny list, the client using the username is blocked.

The API JSON file shipped with ASE is compatible with earlier versions of API JSON files. ASE automatically adds an optional username_header parameter to the API JSON file to maintain compatibility.