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

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 17.0.0
Manual Chapter

Working with OpenAPI

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