API Security
You can use your existing OpenAPI (Swagger) specification file to quickly create an Application Security Manager security policy. Use the REST API to upload the specification file. When creating the security policy in the GUI, use the special API Security policy template. This streamlined template and the configurations contained in your OpenAPI specification file eliminate the need for further regular security policy configurations in ASM.
Note: There is no support for OpenAPI file upload when sent with multipart/form-data.
OpenAPI / ASM integration is useful in a CI/CD environment. Using a CI/CD pipeline, the security policy can be regularly and automatically updated.
When using an API Security policy, regular traffic learning is disabled because the expected traffic configurations are already defined in the OpenAPI specification file. However, learning is enabled for the following violation groups:
- HTTP protocol compliance
- Evaluation techniques
- Disallowed file types
- Attack signatures
- Meta characters
When an updated OpenAPI specification file is uploaded, all previous entities not in the updated file are erased from ASM with the exception of signatures and meta characters.
Note: The basePath is used as the API gateway. Therefore, the basePath/path must be configured for the actual server where the API will be deployed. An incorrect basePath will prevent traffic from being routed to ASM.
You can define API Security policy parameters in your OpenAPI specification file instead of in Application Security Manager under Security > Application Security > Parameters > Parameters List > Add Parameter. Certain parameter fields and configurations are disabled in the GUI. They are editable only in the OpenAPI specification file.
If you upload an OpenAPI / Swagger file to define your parameters, the parameter’s Location field is disabled. You must update the parameter location (and any other configurations) in the OpenAPI file and re-upload it. You cannot locally update parameters via the GUI.
Note: The Location option Header and Cookie are specific to OpenAPI parameters.
The Parameter Value Type object displays in the GUI as JSON value. In Parameter Value Type there is the option of Array value, specifying that the parameters are in an array. Array parameters can be used with path, query, header and form parameters, specifying that the parameters can appear in any location. An Array value enables the Serialization Format field. Also in Parameter Value Type there is the option of Object value, specifying that the parameters can appear in any location. This object value is defined in the OpenAPI file and is not editable from the GUI.
There is support for serialization options as defined in Swagger 2.0.
Loading of array=mixed type is not supported. If one of the following constructs is used in the OpenAPI or Swagger file, the file will fail to load. Errors and warning from loading of an OpenAPI file or a Swagger file are written to /ts/log/asm_config_server.log.
-
Example 1
type: array items: oneOf: -type: string -type: integer -
Example 2
# Array of Cats and Dogs type: array items: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' -
Example 3
type: array items: {}
You should not manually create allowed HTTP URLs in the GUI when working with an API Security policy template and Swagger file. Include the allowed HTTP URLs in the your Swagger file.
.
Note: The URL attribute operationId can be used to filter traffic events related to a URL.
Note: Attribute Body is Mandatory will be enabled if requestBody.required is defined as true by the OpenAPI spec for an endpoint.
You can create a JSON schema validation file to validate for your REST endpoints and protect POST requests.
When writing your JSON schema, be strict with what is permitted and prohibited. Because even a strict schema can still generate false positives, ASM does not include traffic learning of the JSON schema traffic.
The JSON schema is validated when uploaded and any violations are noted. You can use more than 1 JSON schema file but each file must be uploaded separately and the JSON Profile Properties updated after each upload.
Note: When using more than 1 JSON schema file, upload the file with include links first. An error is generated but uploading the subsequent files resolves the broken links error.
After a JSON schema is uploaded and selected, the Parse Parameters setting is disabled because the policy stops using any configured policy parameters and begins using the JSON parameters.
You use the API Security policy template and upload your OpenAPI configuration file to create an OpenAPI security policy.
-
On the Main tab, click Security > Application Security > Security Policies > Policies List.
The Policies List screen opens.
-
Click Create New Policy.
You only see this button when no policy is selected.
-
Enter a unique policy name.
-
Make sure the Policy Type is Security.
-
For the Policy Templateselect API Security.
The OpenAPI (Swagger) File field is now visible.
-
Click Upload File to navigate to your OpenAPI specification file and upload it.
-
Click Save to create the OpenAPI Security policy.
JSON Web Token (JWT) is a compact and self-contained way to represent information between two parties in a JSON (JavaScript Object Notation) format and is commonly used for authentication and authorization. With your API security policy it is possible to control access to its application using JWT validation. your security policy validates the authenticity and well-formedness of JWTs coming from a client, denying access to the service exclusively when the validation process fails. JWT is mainly used for API access.
When a user logs in to a web application, they might receive a JWT, which can then be included in subsequent requests to the server. The server can validate the JWT to ensure that the user is authenticated to access the requested resources.
ASM provides JSON Web Token (JWT) protection. Your ASM policy settings will handle the token for the application. This includes:
- Validating the token’s existence and ensuring its correct structure for specific URLs.
- Verifying the token’s signature based on provisioned certificates.
- Checking the validity period of the token.
- Extracting the user identity from the token and using it for logging and session awareness.
The JSON Web Token consists of three parts: the Header, Claims and Signature. The first two parts are in JSON and Base64 encoded when carried in a request. The three parts are separated by a dot “.” delimiter and put in the authorization header of type “Bearer”, but can also be carried in a query string parameter.
- Header: It contains information about the type of token (usually “JWT”) and the cryptographic algorithm being used to secure the JSON Web Signature (JWS).
- Claims: This refers to the statements or assertions about an entity (typically, the user) that the token is issued for. Claims are key/value pairs contained within the token’s payload. These claims provide information about the JWT and can be used by the recipient to verify the token’s authenticity and determine its validity. Additionally, you can include custom claims in the payload to carry additional information specific to your application.
- Signature: To create the signature part, the header and payload are encoded using a specified algorithm and a secret key. This signature can be used to verify the authenticity of the token and to ensure that it has not been tampered with during transmission. The signature is computed based on the algorithm and the keys used and also Base64-encoded.
Support limitations for types of JSON Web Tokens:
JWS content can be digitally signed. The following algorithm is supported:
- RSA/SHA-256
The following is an example of a header of a JWT with a supported digital signature:
{
"alg": "RS256",
"typ": "JWT"
}Before you begin ensure the following:
-
Before you configure the policy, you need to configure one or more virtual servers to specify where to direct the application requests.
-
Ensure you have created a JSON Web Token, and have saved locally the JSON Web Token information from the IdP server. If your JWT is digitally signed, ensure the supported digital signature RSA-R256 asymmetric algorithm key type is used. See the sample header of a JWT signed with a supported encryption algorithm:
{ "alg": "RS256", "typ": "JWT" }
Create a policy with an Access Profile to configure JSON Web Token (JWT) authentication. The Access Profile can then be applied to URLs for enforcement and secure actions with respect to access tokens. It is specifically associated with HTTP URLs and does not have any predefined default profiles. You can apply only one Access Profile per policy.
Note: The following are required steps to create an ASM policy that with an Access Profile. Ensure the policy’s enforcement, learning and other violation settings are configured according to your application security needs.
-
On the main tab, click Security > Application Security > Security Policies > Policies List .
The Policies List screen opens.
-
Click Create New Policy.
You only see this button when no policy is selected.
-
Enter a unique policy name.
-
Make sure Policy Type is Security.
-
For Policy Template, select a template for your policy.
-
For Virtual Server select a virtual server.
-
Click Save to create the new policy.
The policy is saved to the Policies List.
-
Click the policy name of the new policy
-
From the left menu, expand Advanced Protection and select Access Profiles.
-
Click Create.
-
Enter an Access Profile Name.
-
Enter an optional Description of the Access Profile.
-
Select whether or not to check the Maximum Length of the token.
Option Details Any Maximum length of the token is not enforced Length A token that exceeds maximum length (in bytes) is blocked. You can set the maximum length between 10-10,000 bytes. The default is 2,000 bytes. -
Select whether or not to Check Validity Periodof the token.
-
Select whether or not to Verify Digital Signatureof the token.
-
From Key File clickUpload File and select the JWT key saved to your local system.
When the upload is complete, you will see the JWT file name in the Key File field.
-
Set the Parameter Location of where the token is expected. The default value is Header.
-
Enter the Parameter or Header Name if the parameter is not set to Header.
-
Select whether or not to Extract Username from the token.
-
If the username extraction is enabled, select whether or not the token’s Username is Mandatory.
-
Enter the Username Claim Property from which the token name is extracted, if applicable.
-
Click Add.
The Access Profile is added to the policy.
-
Click Apply Policy to the top right of the screen.
The changes to your policy are deployed.
You have created and deployed an ASM policy with JSON Web Token protection.
One you configure your policy, you can fine tune your learning and blocking settings for JWT authentication and add allowed URLs.
Before you begin ensure you have created an ASM policy with an Access Profile.
Configure the learning and blocking requirements for JSON Web Token (JWT) protection for policy building. There are three violations that you can configure:
- Missing Access Token: The request contains the access token for the respective URL according to the Access Profile. The violation is raised when that token is not found.
- Malformed Access Token: The request’s access token for the URL was malformed.
- Access token does not comply with the profile requirements: The request’s access token failed one or more enforcement checks according to the Access Profile.
-
On the main tab, clickSecurity > Application Security > Policy Building > Learning and Blocking Settings .
The Learning and Blocking screen opens
-
In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
-
Expand the Sessions and Logins section.
This section includes the three access token violations listed previously:
- Missing Access Token
- Malformed Access Token
- Access token does not comply with the profile requirements
-
Review each of the Policy Building Settings so you understand how the security policy handles requests that cause the associated violations, and adjust if necessary. You need to expand most of the settings to see the violations.
Tip: To the right of Policy Building Settings, click Blocking Settings to see and adjust all of the violations at once.
Option What happens when selected Learn The system generates learning suggestions for requests that trigger the violation (except learning suggestions are not generated for requests that return HTTP responses with 400 or 404 status codes). Alarm When selected, the system marks requests that trigger the violation as illegal. The system also records illegal requests in the Charts screen, the system log (/var/log/asm), and possibly in local or remote logs (depending on the settings of the logging profile). Block The system blocks requests that trigger the violation when (1) the security policy is in the blocking enforcement mode, (2) a violation occurs, and (3) the entity is enforced. The system sends the blocking response page (containing a Support ID to identify the request) to the client. -
Click Save to save your changes.
-
Click Apply Policy to the top right of the screen and click OK to confirm your changes.
The changes to your policy are deployed.
You have configured enforcement settings for access token violations.
Add allowed URLs that require JWT protection.
Before you begin, you must configure an ASM policy with an Access Profile that authenticates JSON Web Token (JWT) protection.
-
On the main tab, click Security > Application Security > URLs > Allowed URLs .
The Allowed HTTP URLs screen opens.
-
In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
-
Click Create
The New Allowed HTTP URL screen opens
-
For URL, choose a type and protocol, and then type the URL name or wildcard.
Option Description Explicit Specifies a unique URL, such as /index.html. Wildcard Specifies that the URL is a wildcard expression. Any URL that matches the wildcard expression is considered legal. The pure wildcard (*) is automatically added to the security policy so you do not need to add it. But you can add other wildcards such as /main/*. -
Select HTTPS and type a URL or wildcard expression in the adjacent field.
-
To view more options, next to Create New Allowed URL, select Advanced.
-
From the Access Profile field, select the Access Profile from your policy.
-
Click Create to the bottom left of the table.
The Allowed URLs screen opens and lists the new URL.
-
To put the security policy changes into effect immediately, click Apply Policy.
The security policy allows requests for the URL or URLs matching the wildcard that you added.