Extract user information from JWT in inline mode

API Security Enforcer (ASE) supports the decoding of transparent JSON Web Token (JWT)s received as part of application programming interface (API) requests. It extracts the user information from the JWT and logs it in the ASE access logs. The API Behavioral Security (ABS) AI engine analyzes these access logs to detect attacks and anomalies.

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

A diagram of the traffic flow when ASE is in inline mode that shows the request and response flows between clients, ASE, and the resource server.

A JWT consists of three parts, header, payload, and signature, concatenated with periods (.). The following image shows a sample JWT structure.

An example of JWT showing the header, payload, and signature, concatenated with periods.

ASE decodes the payload to extract user information from a JWT. ASE can decode JWTs received as part of request headers or query strings. In inline mode, ASE supports Bearer and MAC schemes in the Authorization header.

ASE decodes the JWTs and extracts the user information. It does not validate JWTs.

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.

ASE supports arrays only for username claims in the payload. It does not support arrays in clientid or location claims.

When ASE is deployed in inline mode, it decodes the JWTs only when the username and location values are configured in an API JSON file for the API.

If the JWT decoding fails, the API request is not blocked. ASE logs the metadata in the access logs.

The API JSON file

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 inline 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"
    }
  }
}

The values assigned to username and clientid must be different.

The following table describes the parameters in the JWT object of API JSON file.

Parameter Description

Parameter	Description
`location`	The JWT location in an API request. Configure the parameter with a value applicable to your API. The supported values for the `location` parameter are: `qs: <key name>` Set the location parameter with this value when JWT occurs as part of a query string and substitute the <key name> 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: <custom header name>` Set the location parameter with this value when JWT is part of a custom header and substitute the <custom header name> 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:Authorization:MAC` Set the location parameter with this value when JWT is part of Authorization header, with MAC scheme. For example, `"location":"h:Authorization:MAC"`. Authorization: MAC id="eyJhbGcI1NiI", nonce="272095:dp63hm5s", mac="PNPQW4mg43cjQfEpUs3QWub4o6xE=" `h:cookie:<cookie key>` Set the location parameter with this value when JWT occurs as part of a cookie and substitute the <cookie key> with the cookie name. For example, `"location":"h:cookie: access_token"`. Cookie: access_token=eyJhbGiIsI.eyJpc3MiOiJodHRwczotcGxlL.mFrs3ZodqKP4F1cB
`username`	The JWT claim to extract the username.
`clientid`	The JWT claim to extract the client-id.

location

The JWT location in an API request. Configure the parameter with a value applicable to your API.

The supported values for the location parameter are:

qs: <key name>: Set the location parameter with this value when JWT occurs as part of a query string and substitute the <key name> 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: <custom header name>: Set the location parameter with this value when JWT is part of a custom header and substitute the <custom header name> 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:Authorization:MAC: Set the location parameter with this value when JWT is part of Authorization header, with MAC scheme. For example, "location":"h:Authorization:MAC".

Authorization: MAC id="eyJhbGcI1NiI",
               nonce="272095:dp63hm5s",
		     mac="PNPQW4mg43cjQfEpUs3QWub4o6xE="

h:cookie:<cookie key>: Set the location parameter with this value when JWT occurs as part of a cookie and substitute the <cookie key> with the cookie name. For example, "location":"h:cookie: access_token".

Cookie: access_token=eyJhbGiIsI.eyJpc3MiOiJodHRwczotcGxlL.mFrs3ZodqKP4F1cB

username

The JWT claim to extract the username.

clientid

The JWT claim to extract the client-id.

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.

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 inline mode.

The 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. 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 API JSON has an incomplete JWT object and describes its impact on the APIs discovered by ABS in your environment.

Scenarios	Behavior of ASE	Impact on API discovery
A JWT object is not configured in API JSON.	ASE processes the 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": "" }
A JWT object is configured in API JSON file but with no keys. For example. “jwt”:{}	ASE does not process the API JSON file.	The API is not discovered.
A JWT object is configured with all the keys present but with no values set. For example. "jwt": { "username": "", "clientid": "", "location": "" }	ASE processes the 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 API JSON file.	The API is not discovered.

Scenarios

Behavior of ASE

Impact on API discovery

A JWT object is not configured in API JSON.

ASE processes the 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": ""
        }

A JWT object is configured in API JSON file but with no keys. For example.

“jwt”:{}

ASE does not process the API JSON file.

The API is not discovered.

A JWT object is configured with all the keys present but with no values set. For example.

"jwt": {
          "username": "",
          "clientid": "",
          "location": ""
        }