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.
A JWT consists of three parts - header, payload, and signature. They are concatenated with periods(.). The following is a sample JWT structure.
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.
{
“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.
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.The following is an example snippet 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": 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"
}
}
}
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:
|
username | It is the JWT claim to extract the username. |
clientid | It is the JWT claim to extract the client identifier. |
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.
|
When a JWT object is configured in the
root
API JSON file, but with no keys. For example.
|
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.
|
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.
|
When a JWT object is configured but not all keys are set. For
example.
|
ASE does not process the root API
JSON file. |
The API is not discovered. |