PingIntelligence

Extract username from custom header in sideband mode

This topic discusses the extraction of username from a custom header when API Security Enforcer (ASE) is in sideband 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 the API Behavioral Security (ABS) AI Engine to detect attacks.

Following is an example snippet of username information logged to 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

When deployed in sideband mode, ASE receives the application programming interface (API) request information from the sideband policy and extracts the metadata like user information, Internet Protocol (IP) addresses and so on. The following diagram shows the traffic flow when ASE is in sideband mode.

Diagram showing the traffic flow when ASE is deployed in sideband mode

The sideband policy sends user information in a user_info object to ASE. If the user_info object contains username, then ASE extracts it. Otherwise, ASE checks the API JSON configuration.

The API JSON can be configured to extract username from either a JSON Web Token (JWT) or a custom header. ASE first checks the JWT object. If it is configured, then ASE extracts the username from the JWT in an incoming request. If theJWT object is not configured, then ASE checks the username_header parameter configuration in the API JSON file. If it is set, ASE extracts the username from the custom header that comes as part of an incoming request. For more information, see Configure API JSON section.

Image of flowchart for determining in JWT object is configured

ASE supports extracting username from either JWTs or 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 sideband mode.

API JSON configuration in sideband 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 theusername_header parameter to the custom header name containing the username. The following is an example snippet of an API JSON file.

{
    "api_metadata": {
        "protocol": "http",
        "url": "/",
        "cookie": "JSESSIONID",
        "hostname": "*",
        "oauth2_access_token": false,
        "apikey_qs": "",
        "apikey_header": "",
        "enable_blocking": true,

        "cookie_idle_timeout": "200m",
        "logout_api_enabled": false,
        "cookie_persistence_enabled": false,
        "login_url": "",
        "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_check_headers": {},
        "server_ssl": false,
        "servers": [],
        "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 sideband 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 optionalusername_header parameter to the API JSON file to maintain compatibility.