Manual Chapter : Per-Request Policy Configuration for SWG

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0
Manual Chapter

Per-Request Policy Configuration for SWG

Overview: Configuring a per-request policy for SWG

A per-request policy must specify the logic that determines how to process URL requests whether they are requests for web access. How to make that determination is largely up to you.

To put SSL forward proxy bypass (specified in client and server SSL profiles) into effect, the per-request policy must ultimately determine whether to intercept or bypass the SSL traffic. If you plan to process SSL traffic, configure the policy to complete that processing first.

To put URL categorization into effect, the per-request policy must be configured to look up the URL category and assign the URL filter that allows or blocks URL requests.

To base processing of URL requests on a user group or user class, per-request policy items that look up a user group or user class read values stored in session variables. To ensure that the values are available, the access policy that creates the session must be configured with actions that populate the session variables.

Task summary

After you create the per-request policy, use any of the remaining tasks to add items to it to build the per-request policy that you need.

Task list

Creating a per-request policy

You must create a per-request policy before you can configure it in the visual policy editor.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. Click Create.
    The General Properties screen displays.
  3. In the Name field, type a name for the policy and click Finished.
    A per-request policy name must be unique among all per-request policy and access profile names.
    The policy name appears on the Per-Request Policies screen.

Processing SSL traffic in a per-request policy

To use SSL forward proxy bypass in a per-request policy, both the server and client SSL profile must enable SSL forward proxy and SSL forward proxy bypass; and, in the client SSL profile, the default bypass action must be set to Intercept.
Important: Configure a per-request policy so that it completes processing of HTTPS requests before it starts the processing of HTTP requests.
Note: These steps describe how to add items for controlling SSL web traffic to a per-request policy; the steps do not specify a complete per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. To process the HTTPS traffic first, configure a branch for it by adding a Protocol Lookup item at the start of the per-request policy.
    1. Click the (+) icon anywhere in the per-request policy to add a new item.
      A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
    2. In the Search field, type prot, select Protocol Lookup, and click Add Item.
      A properties popup screen opens.
    3. Click Save.
      The properties screen closes. The visual policy editor displays.
    The Protocol Lookup item provides two default branches: HTTPS for SSL traffic and fallback.
  4. Before you add an SSL Bypass Set, or an SSL Intercept Set, item to the per-request policy, you can insert any of the following policy items to process SSL traffic:
    • AD Group Lookup
    • LDAP Group Lookup
    • LocalDB Group Lookup
    • RADIUS Class Lookup
    • Dynamic Date Time
    • Logging
    • Category Lookup
      Important: Category Lookup is valid for processing SSL traffic only when configured for SNI or Subject.CN categorization input and only before any HTTP traffic is processed.
    If you insert other policy items that inspect the SSL payload (HTTP data) before an SSL Bypass Set item, the SSL bypass cannot work as expected.
  5. At any point on the HTTPS branch where you decide to bypass SSL traffic, add an SSL Bypass Set item.
The per-request policy includes items that you can use to complete the processing of SSL traffic. Add other items to the policy to control access according to your requirements.
A per-request policy goes into effect when you add it to a virtual server.

Configuring policies to branch by local database user group

If you plan to look up local database groups from the per-request policy, you must configure local database-related items in the access policy and the per-request policy to use the same session variable.
  1. On the Main tab, click Access Policy > Access Profiles .
    The Access Profiles List screen opens.
  2. In the Access Policy column, click the Edit link for the access profile you want to configure.
    The visual policy editor opens the access policy in a separate screen.
  3. On an access policy branch, click the (+) icon to add an item to the access policy.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  4. In the search field, type local, select Local Database, and click Add Item.
    A popup properties screen opens.
  5. Configure properties for the Local Database action:
    1. From the LocalDB Instance list, select a local user database.
    2. Click Add new entry
      A new line is added to the list of entries with the Action set to Read and other default settings.
    3. In the Destination column in the Session Variable field, type the name of the variable in which to store the user groups retrieved from the local database.
      In the per-request policy, the default value that the LocalDB Group Lookup item uses is session.localdb.groups. If you enter a differentvalue, note it. You will need it to update the advanced expression in the LocalDB Group Lookup item in the per-request policy.
    4. In the Source column from the DB Property list, select groups.
    5. Click Save.
      The properties screen closes. The visual policy editor displays.
    This is not a complete access policy, but you can return to it and complete it later. You can close the visual policy editor or leave it open.
    The access policy includes a Local Database action that can read groups into a session variable.
  6. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  7. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  8. Click the (+) icon anywhere in the per-request policy to add a new item.
  9. In the search field, type local, select LocalDB Group Lookup, and click Add Item.
    A popup properties screen opens.
  10. Click the Branch Rules tab.
  11. Click the change link in the entry for the default expression.
    A popup screen opens.
  12. If the session variable you typed in the access policy Local Database action was session.localdb.groups, perform these substeps.
    1. In the User is a member of field, remove MY_GROUP and type the name of a group.
    2. Click Finished.
      The popup screen closes.
    3. Click Save.
      The properties screen closes and the visual policy editor displays.
  13. If you typed a session variable other than session.localdb.groups in the access policy Local Database action, perform these substeps.
    1. Click the Advanced tab.
      In the field, this expression displays. expression is expr { [mcget {session.localdb.groups}] contains "MY_GROUP" }
    1. In the expression, replace session.localdb.groups with the name of the session variable you typed into the Local Database action.
    2. In the expression, replace MY_GROUP with the name of a group that should match a local database group.
    3. Click Finished.
      The popup screen closes.
    4. Click Save.
      The properties screen closes and the visual policy editor displays.
    This is not a complete per-request access policy, but you can return to it and complete it later.
The access and per-request policies are configured to use the same session variable. The access policy is configured to support the use of LocalDB Group Lookup in the per-request policy.
Complete the configuration of the access and per-request policies.

Specifying URL categorization in a per-request policy

Look up the category for a URL request and assign a URL filter that blocks or allows access to control access to the web, based on the category of the URL request.
Important: This task includes some references to category lookup options and policy items that are supported only on a BIG-IP® system with an SWG subscription. They are: standard categories, SafeSearch support, and content scanning (Response Analytics).
Note: This task provides the steps for adding items to control web traffic based on the URL category. It does not specify a complete per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. Add a Category Lookup item.
    Important: A Category Lookup item triggers event logging for SWG, provides a response web page for the Response Analytics item (on systems that support it), and provides categories for the URL Filter Assign item.
    1. Select an entry from the Categorization Input list based on the type of traffic to be processed. For HTTP traffic, select Use HTTP URI (cannot be used for SSL Bypass decisions). For SSL-encrypted traffic, select either Use SNI in Client Hello (if SNI is not available, use Subject.CN) or Use Subject.CN in Server Cert.
      On a BIG-IP® system with an SWG subscription, if you select Use HTTP URI (cannot be used for SSL Bypass decisions), the SafeSearch Mode list displays and Enabled is selected.
    2. From the Category Lookup Type list, select the category types in which to search for the requested URL. On a system with user-defined categories only, the Process custom categories only item is the only choice. Otherwise, select one from Custom categories first, then standard categories if not found, Always process full list of both custom and standard categories, or Process standard categories only.
      Depending on the selection, the item looks through custom categories or standard categories or both, and compiles a list of one or more categories from them. The list is available for subsequent processing by the URL Filter Assign item.
    3. Click Save.
      The properties screen closes. The visual policy editor displays.
  4. Add a URL Filter Assign item anywhere on a branch after a Category Lookup item.
    In this item, you must specify a URL filter to apply to the URL categories that the Category Lookup item returned. If the filter specifies the Block action for any URL category, URL Filter Assign blocks the request. If URL Filter Assign does not block the request and the filter specifies the Confirm action for any URL category, URL Filter Assign takes the Confirm per-request policy branch.
  5. To enable Safe Search for SSL-encrypted traffic on a BIG-IP® system with an SWG subscription, add an additional Category Lookup item with these settings:
    1. Specify Use HTTP URI (cannot be used for SSL Bypass decisions) as the Category Lookup Type.
    2. Retain the default setting (Enabled) for SafeSearch Mode.
  6. To trigger inspection of the response web page contents on a BIG-IP® system with an SWG subscription, insert a Response Analytics item on a branch after a Category Lookup item and before a URL Filter Assign item.
    The Category Lookup item supplies a response web page. The URL Filter Assign item blocks the URL request if the Response Analytics item identifies malicious content.
    1. In the Max Buffer Size field, type the number of bytes to buffer.
    2. In the Max Buffer time field, type the number of seconds to retain response data in the buffer.
    3. For the Reset on Failure field, retain the default value Enabled to send a TCP reset if the server fails.
    4. For each type of content that you want to exclude from analysis, click Add new entry and then select a type from the list.
      The All-Images type is on the list by default because images are not scanned.
    5. Click Finished.
      The popup screen closes.
    6. Click Save.
      The popup screen closes. The visual policy editor displays.
Now the per-request policy might include items that look up the URL category and assign a URL filter. You can add other items to the policy to control access according to your requirements.
A per-request policy goes into effect when you add it to a virtual server.

Requiring a user to confirm a request before obtaining access

You might want to postpone allowing access for some URL requests and disallow access unless a user confirms that the request is work-related or otherwise justified.
Note: Typically, a subroutine to confirm a request is placed on the Confirm branch of the URL Filter Assign item.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. Click the Add New Subroutine button.
    A popup screen displays.
  4. From the Subroutine from template list, select Confirm.
    A description of the selected template and the actions in it display.
  5. Click Save.
    The popup screen closes. The heading ([+] Subroutine: Name ) for the subroutine, displays below the main editor.
  6. Expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
  7. Click Subroutine Settings/Rename.
    A popup screen displays.
  8. In the Gating Criteria field, type the name of a per-flow variable that contains a resource or resources.
    Important: If the Gating Criteria field remains blank, the subroutine runs once and applies the same ending to all requests for resources for the duration of the subsession.
    Important: If you specify a per-flow variable as the gating criteria for a subroutine and the per-request policy does not populate it, the subroutine is invalidated and does not run.
    A Category Lookup item that runs before a subroutine populates the perflow.category_lookup. name variables and an Application Lookup item that runs before a subroutine populates the perflow.application_lookup. name variables.
    For example, type perflow.category_lookup.result.url or perflow.application_lookup.result.families, or the name of any documented per-flow variable that returns resources instead of a Boolean result.
  9. Click Save.
    The popup screen closes.
  10. To add a subroutine to the per-request policy, in the main editor click the (+) icon.
    A popup screen opens, displaying tabs such as General Purpose and Logon.
  11. Select the Subroutines tab.
  12. Select a subroutine and click Add Item.
    The popup screen closes. The per-request policy displays the newly added subroutine.
A per-request policy goes into effect when you add it to a virtual server.

Configuring a per-request policy to control access to applications

Access Policy Manager® (APM®) supports a preset group of application families and applications. You can configure your own application filters or use one of the filters that APM provides: block-all, allow-all, and default.
Configure a per-request policy to specify the logic that determines whether to allow access to the applications or application families.
Note: This task provides the steps for adding items to control requests based on the application name or application family or based on an application filter. It does not specify a complete per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. Add an Application Lookup item to the policy.
    1. Click the (+) icon anywhere in the per-request policy to add a new item.
      A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
    2. From the General Purpose tab, select Application Lookup, and click Add Item.
      A Properties popup screen opens.
    3. Click Save.
      The Properties screen closes. The visual policy editor displays. A single branch, fallback, follows the Application Lookup item.
  4. To branch by application family or application name, add branch rules to the Application Lookup item.
    1. Click the name of the application lookup item.
      A Properties popup screen displays.
    2. Click the Branch Rule tab.
    3. Click Add Branch Rule.
      A new entry with Name and Expression settings displays.
    4. Click the change link in the new entry.
      A popup screen opens.
    5. Click the Add Expression button.
      Settings are displayed.
    6. For Agent Sel, select Application Lookup.
    7. For Condition select Application Family or Application Name.
    1. From the list, Application Family is or Application Name is, select a family or name.
    1. Click Add Expression.
      The expression displays.
    2. Continue adding branches and when you are done, click Finished.
      The popup screen closes. The Branch Rules popup screen displays.
    3. Click Save.
      The visual policy editor displays.
    Newly created branches follow the Application Lookup item.
  5. To apply an application filter to the request, add an Application Filter Assign item on a branch somewhere after the Application Lookup item.
    A Properties popup screen displays.
  6. From the Application Filter list, select an application filter and click Save.
    The popup screen closes.
To put the per-request policy into effect, add it to the virtual server.
Important: To support application filtering, classification must be enabled on the virtual server.

Configuring a per-request policy to branch by group or class

Add a group or class lookup to a per-request policy when you want to branch by user group or class.
Note: The access policy must be configured to populate session variables for a group or class lookup to succeed. This task provides the steps for adding items to branch by group or class. It does not specify a complete per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. On a policy branch, click the (+) icon to add an item to the policy.
    A small set of actions are provided for building a per-request policy.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  4. On the Authentication tab, select an option: AD Group Lookup, LDAP Group Lookup, or RADIUS Class Lookup to the per-request policy.
  5. Click Add Item.
    A properties popup screen opens.
  6. Click the Branch Rules tab.
  7. To edit an expression, click the change link.
    An additional popup screen opens, displaying the Simple tab.
  8. Edit the default simple expression to specify a group or class that is used in your environment.
    In an LDAP Group Lookup item, the default simple expression is User is a member of CN=MY_GROUP, CN=USERS, CN=MY_DOMAIN. You can use the simple expression editor to replace the default values.
  9. Click Finished.
    The popup screen closes.
  10. Click Save.
    The popup screen closes. The visual policy editor displays.
A per-request policy goes into effect when you add it to a virtual server.

Blocking outgoing social media requests

This configuration is specific to a BIG-IP® system with an SWG subscription only.
You might want to block outgoing requests to social media, particularly chat requests. To do this, you must insert two items into the per-request policy: Request Analytics followed by URL Filter Assign, after Category Lookup.
  1. Open a per-request policy for editing.
    For example, open a policy that already includes Response Analytics and URL Filter Assign items. Policy: Category Lookup followed by Response Analytics followed by  URL Filter Assign
  2. Click the (+) icon after the Category Lookup item to add a new item.
    A popup screen opens, displaying tabs such as General Purpose and Logon.
  3. On the General Purpose tab, select Request Analytics and click Add Item.
    The popup screen closes. A new popup screen displays the properties for the newly added item.
  4. Click Save.
    The popup screen closes. The newly added item displays in the per-request policy.
  5. Click the (+) icon on the branch after the newly added Request Analytics item.
  6. On the General Purpose tab, select URL Filter Assign and click Add Item.
  7. From the URL Filter list, select a URL filter and click Save.
    Note: A URL Filter Assign must follow the Request Analytics agent in addition to following the Response Analytics agent.
The resulting per-request policy might include these items on a branch: Category Lookup, Request Analytics, URL Filter Assign, Response Analytics, and URL Filter Assign.

About Response Analytics and the order of policy items

Note: The Response Analytics per-request policy item is for use only on a BIG-IP® system with an SWG subscription.

The Response Analytics per-request policy item makes an HTTP request and waits for the HTTP response before it completes. As a result to function properly, any policy items that rely on the information in the HTTP request or that attempt to modify the HTTP request must always precede the Response Analytics item. Specifically, the Category Lookup and HTTP Headers items must not follow a Response Analytics item.

Important: You must enforce this ordering to ensure that your per-request policy functions as you intend.

About SSL Bypass Set and SSL Intercept Set and the order of policy items

To ensure that SSL Bypass Set and SSL Intercept Set work correctly, do not place them in a per-request policy after any of these items:

  • Category Lookup, if configured to use HTTP URI for input
  • Response Analytics
  • URL Filter Assign
  • HTTP Headers
  • Application Lookup
  • Application Filter Assign

About the SSL Bypass Set and SSL Intercept Set process

For SSL bypass or SSL intercept actions, Access Policy Manager® (APM®) forwards the client hello directly to the server. The client and server then negotiate SSL parameters. This must occur before any per-request policy item inspects the SSL payload (HTTP data). Everything that the policy does before an SSL Bypass Set or SSL Intercept Set policy item must operate either on SSL data (certificate or client hello) or on session data (which is not part of SSL payload).

About how to trigger URL request event logging

Unless a per-request policy includes and executes a Category Lookup item, URL request event logging does not occur.

About Safe Search and supported search engines

Note: Safe Search is supported only on a BIG-IP® system with an SWG subscription.

Safe Search is a search engine feature that can prevent offensive content and images from showing up in search results. Safe Search can also protect video searches on Google, Bing, and Yahoo search engines.

Safe Search can be enabled in a per-request policy using the Category Lookup item. Secure Web Gateway (SWG) with Safe Search enabled supports these search engines: Ask, Bing, DuckDuckGo, Google, Lycos, and Yahoo. Some search engines, such as Google and Yahoo, use SSL by default; in this case, Safe Search works only when SWG is configured with SSL forward proxy.

Note: For Safe Search filtering to work correctly, URLs for the supported search engine sites must not be added to a custom category. The search engine's domain must remain categorized in the Search Engines and Portals URL category.

Overview: Requiring additional authentication for sensitive resources

Typically, an access policy verifies endpoint security and authenticates a user before starting an access session. If the user requests access to a sensitive resource after the session is established, you can require additional authentication or revalidation of the credentials for that resource by configuring a per-request policy subroutine.

Task summary

Configuring a per-request policy subroutine

Configure a per-request policy subroutine to prepare it for use in the per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. Click the Add New Subroutine button.
    A popup screen displays.
  4. To preview the available templates, select them one at a time from the Subroutine from template list.
    A description of the selected template and the items in it display.
  5. Select a template and click Save.
    The popup screen closes. The subroutine, with the heading [+] Subroutine: Name , displays below the main editor.
  6. Expand the subroutine by clicking the [+] icon.
    A red asterisk displays by the name of any item that needs some configuration.
  7. Edit the properties of any item as needed.
    If the subroutine includes an AAA authentication item, you must specify an AAA server in the item properties.
Configure any additional items that you require in the subroutine.

Specifying resources for the subroutine to validate and protect

Configure the gating criteria for a per-request policy subroutine to specify the resources associated with the subroutine.
Note: When a subsession for matching resources exists, Access Policy Manager® does not run the subroutine again, but takes the same branch that the subroutine took the last time that it ran.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. Click Subroutine Settings/Rename.
    A popup screen displays.
  3. In the Gating Criteria field, type the name of a per-flow variable that contains a resource or resources.
    Important: If the Gating Criteria field remains blank, the subroutine runs once and applies the same ending to all requests for resources for the duration of the subsession.
    Important: If you specify a per-flow variable as the gating criteria for a subroutine and the per-request policy does not populate it, the subroutine is invalidated and does not run.
    A Category Lookup item that runs before a subroutine populates the perflow.category_lookup. name variables and an Application Lookup item that runs before a subroutine populates the perflow.application_lookup. name variables.
    For example, type perflow.category_lookup.result.url or perflow.application_lookup.result.families, or the name of any documented per-flow variable that returns resources instead of a Boolean result.
  4. Click Save.
    The popup screen closes.
The subroutine is ready to be added to the per-request policy.

Configuring multiple logon attempts for a subroutine

If you are configuring a per-request policy subroutine to obtain additional authentication and you want to provide users with more than one chance to supply credentials, you must configure and assign a Loop terminal.
Note: When you configure the properties for an authentication item in a subroutine, a property to enable multiple logon attempts is not available.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. If Loop does not display in the list of terminals in the heading, add a Loop terminal:
    1. Click Subroutine Settings/Rename.
      A popup screen displays.
    2. From the Maximum Macro Loop Count list, select a value greater than 1.
      The maximum value is 5.
    3. Click Save.
      The popup screen closes. Loop displays in the subroutine heading on the list of terminals.
  3. To create a loop on a branch in the subroutine:
    1. Click the name of an existing terminal.
      A popup screen displays.
    2. Select Loop.
  4. Click Save.
    Note: When you specify Loop as a terminal, it enables repetition of the actions on the branch for up to the specified count. An action that does not complete successfully after the maximum count exits through the Loop terminal onto a Loop branch.
    The popup screen closes.

Adding a subroutine to a per-request policy

Put the subroutine that you configured to use by adding it to the per-request policy.
  1. With the per-request policy open in the visual policy editor, click the (+) icon on a per-request policy branch.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  2. Select the Subroutines tab.
  3. Select a subroutine and click Add Item.
    The popup screen closes and the per-request policy displays in the visual policy editor.
Ensure that the per-request policy includes an action that populates the gating criteria specified in the subroutine properties.

Requesting authentication periodically throughout a session

Check the value of the Maximum Session Timeout setting in the access profile. If it is zero (0), this procedure cannot work.
Configure the subroutine so that it runs periodically during a session, forcing the user to reauthenticate to gain access to resources.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. Click Subroutine Settings/Rename.
    A popup screen displays.
  3. In the Max Subsession Life (sec) field, type a number that is less than the maximum session timeout specified in the access profile.
    The default maximum timeout for a session is one week, 604800 seconds.
    For example, if the session times out after a week and you want users to authenticate every day, type 86400.
  4. In the Gating Criteria field, type the name of a per-flow variable that contains a resource or resources.
    Important: If the Gating Criteria field remains blank, the subroutine runs once and applies the same ending to all requests for resources for the duration of the subsession.
    Important: If you specify a per-flow variable as the gating criteria for a subroutine and the per-request policy does not populate it, the subroutine is invalidated and does not run.
    A Category Lookup item that runs before a subroutine populates the perflow.category_lookup. name variables and an Application Lookup item that runs before a subroutine populates the perflow.application_lookup. name variables.
    For example, type perflow.category_lookup.result.url or perflow.application_lookup.result.families, or the name of any documented per-flow variable that returns resources instead of a Boolean result.
  5. Click Save.
    The popup screen closes.
The subroutine is ready to be added to the per-request policy.