--- title: Extract username from custom header in sideband mode description: 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. component: pingintelligence version: 5.2 page_id: pingintelligence:pingintelligence_reference_guide:pingintelligence_extract_username_custom_header_sideband canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_reference_guide/pingintelligence_extract_username_custom_header_sideband.html revdate: April 3, 2024 section_ids: api-json-configuration-in-sideband-mode: API JSON configuration in sideband mode --- # 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) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* request information from the sideband policy and extracts the metadata like user information, Internet Protocol (IP) *(tooltip: \
\

The method by which data is sent across the internet from the source host to the destination host.\

\
)* 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](../_images/yax1607220398046.png) 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 the`JWT` 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](../_images/xso1608343572522.png) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](pingintelligence_exactract_user_informaton_jwt_sideband.html). | ## 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 the`username_header` parameter to the custom header name containing the username. The following is an example snippet of an API JSON file. ```json { "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](pingintelligence_define_api_json_file_sideband.html). 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. |