--- title: Extract user information from JWT in sideband mode description: ASE supports the decoding of transparent JSON Web Tokens (JWTs) received as part of API requests. It extracts the user information from the JWT and logs it in ASE access logs. The ABS (API Behavioral Security) AI engine analyses these access logs to generate reports and detect attacks. component: pingintelligence version: 5.1 page_id: pingintelligence:api_security_enforcer:pingintelligence_exactract_user_informaton_jwt_sideband canonical_url: https://docs.pingidentity.com/pingintelligence/5.1/api_security_enforcer/pingintelligence_exactract_user_informaton_jwt_sideband.html revdate: April 26, 2024 section_ids: configure-api-json: Configure API JSON --- # Extract user information from JWT in sideband mode ASE supports the decoding of transparent JSON Web Tokens (JWTs) received as part of API requests. It extracts the user information from the JWT and logs it in ASE access logs. The ABS (API Behavioral Security) AI engine analyses these access logs to generate reports and detect attacks. The following diagram shows the traffic flow when ASE is in sideband mode. ![qfi1584171751092](../../5.2/_images/qfi1584171751092.png) A JWT consists of three parts - header, payload, and signature. They are concatenated with periods(**.**). The following is a sample JWT structure. ![eix1584003804748](../../5.2/_images/eix1584003804748.png) ASE decodes the payload to extract user information from a JWT. It can decode JWTs received as part of request headers or query strings. In sideband mode, ASE supports only **Bearer** scheme in the Authorization header. | | | | - | --------------------------------------------------------------------------------------- | | | ASE does not validate JWTs. It just decodes the JWTs and extracts the user information. | ASE supports a list of usernames in JWT. When the username claim in the payload is an array with multiple elements, ASE extracts the first element of the array. The elements in the array can be strings or numbers and the array should be a valid JSON array. ![mkr1599456635172](../../5.2/_images/mkr1599456635172.png) | | | | - | ----------------------------------------------------------------------------------------------------------------------- | | | ASE supports arrays only for username claims in the payload. It does not support arrays in clientid or location claims. | When deployed in sideband mode, ASE receives the API request information from the gateway policy and extracts the metadata. The `user_info` object contains the user information along with other metadata. The following is an example snippet of information received by ASE from API gateway. ```json { "source_ip": "127.0.0.1 ", "source_port": 12345, "method": "GET", "url": "/api3?query=eyJ0eXAiOiJKV1QiLCJhbGciHuDXOyfQqAnoXC4bA&abc=xyz", "http_version": "1.1", "user_info":[\{"username":"abc","client_id":"cabfsghhbsag"}], "headers": [ { "host": "shop.com" }, { "content-type": "application/xml" }, { "content-length": "100" }, { "x-forwarded-for": "dev.pxy.com" }, { "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.110 Safari/537.36" } ] } ``` ASE extracts the user information from the `user_info` object or JWT or both. The following scenarios explain the different ways in which ASE extracts user information: * If the gateway policy sends the `user_info` object with `username` and `clientid`, ASE does not decode the JWT. It extracts the user information from the `user_info` object. * If the gateway policy sends the `user_info` object without `username` and `clientid`, ASE decodes the JWT to extract the information. * If the gateway policy sends the `user_info` object without a `username`, but with `clientid`, ASE decodes the JWT and extracts`username` from the JWT and client identifier from the `user_info` object. * If the gateway policy sends the `user_info` object with a `username`, but without a `clientid`, ASE decodes the JWT to extract `clientid` and captures the`username` from the`user_info` object. * If the gateway policy does not send`user_info` object or sends an invalid `user_info` object, ASE decodes the JWT to extract the`username` and `clientid` information if available. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------- | | | If the JWT decoding fails, the API request is not blocked. ASE logs the information got from the gateway policy in the access logs. | ## Configure API JSON The behavior and properties of your API are defined in an API JSON file in ASE. To enable username capture, set the values for the parameters defined in the JWT object of the API JSON file as per your API setup. For more information, see [Defining an API using API JSON configuration file in sideband mode](pingintelligence_define_api_json_file_sideband.html). The following is an example snippet of an API JSON file. ```json { "api_metadata": { "protocol": "http", "url": "/rest", "hostname": "*", "cookie": "", "cookie_idle_timeout": "200m", "logout_api_enabled": false, "cookie_persistence_enabled": false, "oauth2_access_token": true, "apikey_qs": "", "apikey_header": "", "login_url": "", "enable_blocking": true, "api_mapping": { "internal_url": "" }, "username_header": "", "jwt": { "location": "h:authorization:bearer", "username": "username", "clientid": "client_id" } } } ``` | | | | - | ---------------------------------------------------------------- | | | The values assigned to `username` and `clientid` cannot be same. | The following table explains the parameters in the JWT object of API JSON file. | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location` | `location` is the place of occurrence of JWT in an API request. Configure the parameter with a value applicable to your API.The supported values for **location** parameter are:- **`qs:`** - Set the location parameter with this value when JWT occurs as part of a query string and substitute the \ with the query string parameter. For example,`"location": "qs: access_token"`. ``` https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q ``` - **`h:`** - Set the location parameter with this value when JWT is part of a custom header and substitute the \ with custom header. For example,`"location": "h:X-jwt-header"`. ``` X-jwt-header: eyJhbGcUzI1NiI.eyJzDkwIG4gRG9xpZWQiOjwMjJ9.DWw5PDZEl-g ``` - **`h:Authorization:bearer`** - Set the location parameter with this value when JWT is part of Authorization header, with bearer scheme. For example, `"location": "h:Authorization:bearer"`. ``` Authorization: Bearer eyJhbGIUzIiI.eyJzdiIxG4gRG9lIiwiZiOjJ9.DWPwNDZEl-g ``` - **`h:cookie:`** - Set the location parameter with this value when JWT occurs as part of a cookie and substitute the \ with the cookie name. For example, `"location": "h:cookie: access_token"`. ``` Cookie: access_token=eyJhbGiIsI.eyJpc3MiOiJodHRwczotcGxlL.mFrs3ZodqKP4F1cB ``` | | `username` | It is the JWT claim to extract the username. | | `clientid` | It is the JWT claim to extract the client identifier. | When `enable_blocking` is set to`true`, ASE checks the username against the list of usernames in the whitelist and blacklist. If the username is in the blacklist, the client using the username is blocked. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | ASE also supports extracting Username from a custom HTTP header. However, you can configure Username capture from either custom header or JWT, but not both. For more information, see [Extract username from custom header in sideband mode](pingintelligence_extract_username_custom_header_sideband.html). | **API discovery process -**The ABS AI Engine processes the ASE access logs and discovers new and unknown APIs in your environment. A root API JSON is defined in ASE to enable API discovery by ABS. For more information on API discovery, see [API discovery and configuration](../abs_ai_engine/pingintelligence_api_discovery_configuration.html). If the root API JSON has a JWT object configured with values set for all the keys, then the APIs discovered by the ABS will have the JWT object. The following table explains the behavior of ASE when the root API JSON has an incomplete JWT object. It also describes its impact on the APIs discovered by ABS in your environment. | Scenarios | Behavior of ASE | API discovery | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | When a JWT object is not configured in `root` API JSON. | ASE processes the `root` API JSON file. | A JWT object gets added to the discovered APIs with all the keys but empty values. For example.``` "jwt": { "username": "", "clientid": "", "location": "" } ``` | | When a JWT object is configured in the `root` API JSON file, but with no keys. For example.``` "jwt":{} ``` | ASE does**not** process the `root` API JSON file. | The API is not discovered. | | When a JWT object is configured with all the keys present but no values set. For example.``` "jwt": { "username": "", "clientid": "", "location": "" } ``` | ASE processes the `root` API JSON file. | A JWT object gets added to the discovered APIs with all the keys but empty values. For example.``` "jwt": { "username": "", "clientid": "", "location": "" } ``` | | When a JWT object is configured but not all keys are set. For example.``` "jwt": { "username": "", "location": "" } ``` | ASE does **not** process the `root` API JSON file. | The API is not discovered. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The API JSON file shipped with ASE is compatible with earlier versions of API JSON files. ASE automatically adds an empty JWT object to the API JSON file to maintain compatibility. |