Manual Chapter :
Adding JSON Support to an Existing Security Policy
Applies To:
Show Versions![Show Versions](/etc/designs/pcx/techdocs/images/expandversions.gif)
BIG-IP APM
- 16.1.5
BIG-IP ASM
- 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0
Adding JSON Support to an Existing Security Policy
Overview: Adding JSON support to existing security policies
JSON (JavaScript® Object Notation) is a data-interchange format often used
to pass data back and forth between an application and a server. This implementation describes
how to add JSON support to an existing security policy for an application that uses JSON for data
transfer. You create a JSON profile to define what the security policy enforces and considers
legal when it detects traffic that contains JSON data.
You add JSON support to a security policy by completing these tasks.
Creating a JSON profile
Before you can complete this task, you need to have already created a security
policy for your application.
This task describes how to create a JSON profile that defines the properties that
the security policy enforces for an application sending JSON payloads or WebSocket
payloads in JSON format.
The system supports JSON in UTF-8 and UTF-16
encoding. WebSocket allows only UTF-8.
- On the Main tab, click.
- ClickCreateto create a new JSON profile, or edit theDefaultJSON profile (by clicking it).The Create New JSON Profile screen opens.
- Type a name for the profile.
- Adjust the maximum values that define the JSON data for the AJAX application, or use the default values.
- If you want the system to tolerate and not report warnings about JSON content, select theTolerate JSON Parsing Warningscheck box.If the system cannot parse JSON content, it generates the violationMalformed JSON data, regardless of whether this setting is enabled or disabled.
- To parse parameters in a JSON payload as parameters (recommended), ensure thatParse Parametersis enabled.The system extracts parameters from JSON content whenever the JSON profile is used; for example, with URLs, WebSocket URLs, or parameters that use a JSON profile.The security policy parses parameters extracted from the JSON payload the same as other parameters. Also, the Attack Signatures, Value Metacharacters, and Sensitive Data Configuration tabs are removed from the screen, so you can skip to the last step.
- If the signatures included in the security policy are not sufficient for this JSON profile, you can change them.
- On the Attack Signatures tab, in theGlobal Security Policy Settingslist, select any specific attack signatures that you want to enable or disable for this profile, and then move them into theOverridden Security Policy Settingslist.If no attack signatures are listed in theGlobal Security Policy Settingslist, create the profile, update the attack signatures, then edit the profile.
- After you have moved any applicable attack signatures to theOverridden Security Policy Settingslist, enable or disable each of them as needed:
- Enabled- Enforces the attack signature for this JSON profile, although the signature might be disabled in general. The system reports the violationAttack Signature Detectedwhen the JSON in a request matches the attack signature.
- Disabled- Disables the attack signature for this JSON profile, although the signature might be enabled in general.
- To allow or disallow specific meta characters in JSON data (and thus override the global meta character settings), click the Value Meta Characters tab.
- Select theCheck characterscheck box, if it is not already selected.
- Move any meta characters that you want allow or disallow from theGlobal Security Policy Settingslist into theOverridden Security Policy Settingslist.
- In theOverridden Security Policy Settingslist, change the meta character state toAlloworDisallow.
- To mask sensitive JSON data (replacing it with asterisks), click the Sensitive Data Configuration tab.
- In theElement Namefield, type the JSON element whose values you want the system to consider sensitive.
- ClickAdd.
If the JSON data causes violations and the system stops parsing the data part way through a transaction, the system masks only the sensitive data that was fully parsed.Add any other elements that could contain sensitive data that you want to mask. - ClickCreate(orUpdateif editing the Default profile).The system creates the profile and displays it in the JSON Profiles list.
This creates a JSON profile that affects the security policy when you associate the
profile with a URL, WebSocket URL, or parameter.
Next, you need to associate the JSON profile with any URLs, WebSocket URLs, or
parameters that might include JSON data.
Associating a JSON
profile with a URL
Before you can associate a JSON profile with a URL, you need to have created a security
policy with policy elements including application URLs, and the JSON profile.
You can associate a JSON profile with one or more
explicit or wildcard URLs.
- On the Main tab, click.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- From the Allowed URLs List, click the name of a URL that might contain JSON data.The Allowed URL Properties screen opens.
- Next toAllowed URL Properties, selectAdvanced.The screen refreshes to display additional configuration options.
- Click theHeader-Based Content Profilestab, and in theRequest Header Namefield, type the explicit string or header name that defines when the request is treated as theParsed Astype; for example,content-type.This field is not case sensitive.If the URL always contains JSON data, forRequest Body HandlingselectJSON.
- In theRequest Header Valuefield, type the wildcard (including *, ?, or [chars]) for the header value that must be matched in theRequest Header Namefield; for example,*json*.This field is case sensitive.
- From theRequest Body Handlinglist, selectJSON.The system automatically creates aDefaultJSON profile, and assigns it as the profile when you selectJSONin this field.
- From theProfile Namelist, either leave the default, select a JSON profile appropriate for this URL, or clickCreateto quickly create a new JSON profile.
- ClickAdd.Add as many header types as you need to secure this URL, clickingAddafter specifying each one.
- To override the global meta character settings for this URL, adjust the meta character policy settings:
- In the Meta Characters tab, select theCheck characters on this URLcheck box, if it is not already selected.
- Move any meta characters that you want allow or disallow from theGlobal Security Policy Settingslist into theOverridden Security Policy Settingslist.
- In theOverridden Security Policy Settingslist, change the meta character state toAlloworDisallow.
- ClickUpdate.
- To put the security policy changes into effect immediately, clickApply Policy.
The JSON profile is associated with the URL.
Continue to associate JSON profiles with any URLs
in the application that might contain JSON data.
Associating a JSON
profile with a parameter
You need to have created a security policy with policy elements including parameters
and a JSON profile before starting this procedure.
You can associate a JSON profile with a
parameter.
- On the Main tab, click.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- In the Parameters List area, click the name of a parameter to which to assign a JSON profile.The Parameter Properties screen opens.
- For theParameter Value Typesetting, selectJSON value.The system automatically creates aDefaultJSON profile, and assigns it as the profile when you selectJSON valuein this field.
- From theJSON Profilelist, either leave the default, select a JSON profile appropriate for this parameter, or clickCreateto quickly create a new JSON profile for this parameter.
- ClickUpdate.The system associates the JSON profile with the parameter.
- To put the security policy changes into effect immediately, clickApply Policy.
Continue to associate JSON profiles with any
parameters in the application that might contain JSON data.
Implementation result
You have manually added JSON support to the active security policy. The policy can now secure applications that use JSON for data transfer between the client and the server. If web application traffic includes JSON data, the system checks that it meets the requirements that you specified in the JSON profile.
Using a Custom JSON Schema
Using a custom JSON schema
You can use your own JSON schema validation file(s)
for your REST endpoints rather than policy parameter configurations. The REST endpoint
is defined as <method, path>, e.g. PATCH /product/order. The custom JSON schema is
validated when uploaded and any violations are noted. You can use more than one JSON
schema file but each file must be uploaded separately, with the main schema file
uploaded first, and the JSON Profile Properties updated after each upload.
- On the Main tab, click.
- Select an existing profile or clickCreate.
- In theJSON Schema Filessection, clickChoose Fileand select your custom JSON schema file.When using more than 1 JSON schema file, upload the main schema file, i.e. with$reflinks, first. An error is generated but uploading the subsequent files resolves the broken links error.
- ClickUpload.
- Continue to choose and upload JSON schema files are needed.
- ClickCreateif this is a new profile orUpdateif editing an existing profile.
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 custom JSON parameters from the JSON schema
file(s).
If you created a new JSON profile, you need to
associate it with any parameters, HTTP URLs or WebSocket URLs that might include JSON
data.
Assigning a JSON profile to an HTTP URL
A JSON schema can be assigned to an HTTP URL to
provide JSON schema validation for a REST endpoint.
- On the Main tab, click.
- In theCurrent edited policylist near the top of the screen, verify that the policy shown is the one you want to work on
- Select an existing Allowed HTTP URL or clickNew Allowed HTTP URL.
- BesideCreate New Allowed URLselectAdvanced.
- Open theHeader-Based Content Profiletab.
- Enter aRequest Header NameandRequest Header Value.
- ForRequest Body Handlingselect JSON.
- ForProfile Nameselect the JSON profile and clickAdd.Continue to select and add JSON profiles as needed to the Allowed HTTP URL.
- Use theUpandDownbuttons to change the order of the Request Header Names which is the order in which the system checks header content of requests for this URL.
- If you are configuring a new Allowed HTTP URL, continue to configure the URL properties as needed.
- ClickCreate.
The HTTP URL now includes JSON schema validation for
REST endpoints.
Assigning a JSON profile to a WebSocket URL
A JSON schema can be assigned to a WebSocket URL to
provide JSON schema validation for a REST endpoint.
- On the Main tab, click.The Allowed WebSocket URLs screen opens.
- In theCurrent edited policylist near the top of the screen, verify that the policy shown is the one you want to work on.
- Select an existing WebSocket URL or clickCreate.
- On the Message Handling tab, ensure thatCheck Message Payloadis enabled.
- ForAllowed Message Payload FormatsselectJSON.
- ForPayload Enforcementselect the JSON Profile to use.
- If you are configuring a new WebSocket URL, continue to configure the URL properties as needed.
- ClickCreate.