F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Application Security Manager: Implementations
  3. API Security
Manual Chapter : API Security

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 17.5.1, 17.5.0
Manual Chapter

API Security

Working with OpenAPI

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

Working with OpenAPI and security policy parameters

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.

Location

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.
The Location option
Header
 and
Cookie
 are specific to OpenAPI parameters.

Parameter Value Type

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.

Serialization

There is support for serialization options as defined in Swagger 2.0.

Mixed type array

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:  {}

Working with OpenAPI and allowed HTTP URLs

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.
.
The URL attribute
operationId
 can be used to filter traffic events related to a URL.
Attribute
Body is Mandatory
 will be enabled if
requestBody.required
 is defined as
true
 by the OpenAPI spec for an endpoint.

Working with OpenAPI JSON schemas

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

Creating an OpenAPI security policy

You use the API Security policy template and upload your OpenAPI configuration file to create an OpenAPI security policy.
  1. On the Main tab, click
    Security
    Application Security
    Security Policies
    Policies List
    .
    The Policies List screen opens.
  2. Click
    Create New Policy
    .
    You only see this button when no policy is selected.
  3. Enter a unique policy name.
  4. Make sure the
    Policy Type
     is
    Security
    .
  5. For the
    Policy Template
    select
    API Security
    .
    The
    OpenAPI (Swagger) File
     field is now visible.
  6. Click
    Upload File
     to navigate to your OpenAPI specification file and upload it.
  7. Click
    Save
     to create the OpenAPI Security policy.

JSON Web Token (JWT) Protection

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:
  1. Validating the token's existence and ensuring its correct structure for specific URLs.
  2. Verifying the token's signature based on provisioned certificates.
  3. Checking the validity period of the token.
  4. 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"
}

Configuring an ASM Policy to Authenticate a JSON Web Token

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.
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.
  1. On the main tab, click
    Security
    Application Security
    Security Policies
    Policies List
    .
    The Policies List screen opens.
  2. Click
    Create New Policy
    .
    You only see this button when no policy is selected.
  3. Enter a unique policy name.
  4. Make sure
    Policy Type
     is
    Security
    .
  5. For
    Policy Template
    , select a template for your policy.
  6. For
    Virtual Server
     select a virtual server.
  7. Click
    Save
     to create the new policy.
    The policy is saved to the Policies List.
  8. Click the policy name of the new policy
  9. From the left menu, expand
    Advanced Protection
     and select
    Access Profiles
    .
  10. Click
    Create
    .
  11. Enter an
    Access Profile Name
    .
  12. Enter an optional
    Description
     of the Access Profile.
  13. 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.
  14. Select whether or not to
    Check Validity Period
    of the token.
  15. Select whether or not to
    Verify Digital Signature
    of the token.
  16. From
    Key File
     click
    Upload 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.
  17. Set the
    Parameter Location
     of where the token is expected. The default value is
    Header
    .
  18. Enter the
    Parameter or Header Name
     if the parameter is not set to
    Header
    .
  19. Select whether or not to
    Extract Username
     from the token.
  20. If the username extraction is enabled, select whether or not the token's
    Username is Mandatory
    .
  21. Enter the
    Username Claim Property
     from which the token name is extracted, if applicable.
  22. Click
    Add
    .
    The Access Profile is added to the policy.
  23. 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.

Configuring learning and blocking for JSON Web Token Protection

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.
  1. On the main tab, click
    Security
    Application Security
    Policy Building
    Learning and Blocking Settings
    .
    The Learning and Blocking screen opens
  2. 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.
  3. 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
  4. 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.
    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.
  5. Click
    Save
     to save your changes.
  6. 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.

Add allowed URLs for JSON Web Token protection

Before you begin, you must configure an ASM policy with an Access Profile that authenticates JSON Web Token (JWT) protection.
  1. On the main tab, click
    Security
    Application Security
    URLs
    Allowed URLs
    .
    The Allowed HTTP URLs screen opens.
  2. 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.
  3. Click
    Create
    The New Allowed HTTP URL screen opens
  4. 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/*
    .
  5. Select
    HTTPS
      and type a URL or wildcard expression in the adjacent field.
  6. To view more options, next to
    Create New Allowed URL
    , select
    Advanced
    .
  7. From the
    Access Profile
     field, select the Access Profile from your policy.
  8. Click
    Create
     to the bottom left of the table.
    The Allowed URLs screen opens and lists the new URL.
  9. 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.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information