Manual Chapter : Per-Request Policy Concepts and Examples

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1
Manual Chapter

Exporting and importing a per-request policy across BIG-IP systems

Export a per-request policy from one BIG-IP system and import it on another (at the same product version level) to copy a policy across systems.
Note: Before you import a per-request policy from one BIG-IP system to another BIG-IP system, you must first list any custom categories configured on the source system and make sure you have the same custom categories on the target system. Otherwise, import will fail.
  1. On the Main tab, click Access Policy > Per-Request Policies. The Per-Request Policies screen opens.
  2. Click the link in the Export column for the policy that you want to export. A file downloads.
  3. Note the list of custom categories:
    1. Click Access Policy > Secure Web Gateway > URL Categories.
    2. Expand the Custom Categories list.
  4. Log in to the Configuration utility on the BIG-IP system where you want to import the per-request policy.
  5. Verify that the custom categories that exist on the other BIG-IP system also exist on this BIG-IP system:
    1. Click Access Policy > Secure Web Gateway > URL Categories.
    2. Expand the Custom Categories list.
    3. Create any additional custom categories needed to match the list on the other BIG-IP system.
  6. On the Main tab, click Access Policy > Per-Request Policies. The Per-Request Policies screen opens.
  7. Click Import. An Import Policy screen displays.
  8. In New Policy Name, type a name.
  9. For Config File Upload, click Browse, locate and select the file downloaded from the other BIG-IP system.
  10. To reuse objects already existing on this BIG-IP system, select the Reuse Existing Objects check box.
  11. Click Import.

About access and per-request policies

BIG-IP Access Policy Manager Secure Web Gateway (SWG) uses two types of policies.

Access policy
The access policy runs when a client initiates a session. Depending on the actions you include in the access policy, it can authenticate the user and perform group or class queries to populate session variables with data for use throughout the session. It must also specify the SWG scheme to apply to the session.
Per-request policy
After a session starts, a per-request policy runs each time the client makes an HTTP or HTTPS request. A per-request policy must provide the logic for determining how to process web-bound traffic. It must determine whether to allow or reject a URL request and control whether or not to bypass SSL traffic.

An access policy and a per-request policy are both specified in a virtual server.

About per-request policy configuration

A per-request policy can be configured with policy items that support these types of branches and actions.

Branch by protocol, date, time, user group or class
Policy items are available for each type of branch. Protocol lookup can branch to HTTP or HTTPS. Group or class lookup items compare strings that you specify against session variables.
Set the SSL bypass action
The SSL Intercept Set and SSL Bypass Set items set the SSL filter to intercept or bypass SSL traffic. This works in a configuration where SSL forward proxy and SSL forward proxy bypass are enabled in client and server SSL profiles on the virtual server.
Look up categories, enable Safe Search
The Category Lookup item does lookups based on URL for an HTTP request or host name for an HTTPS request. It can also enable Safe Search for HTTP requests.
Analyze response content
A Response Analytics item triggers content analysis of the response web page that the Category Lookup item returns.
Apply URL filters
A URL Filter Assign item assigns a URL filter to apply on the categories that the Category Lookup item found.

About per-request policies and SWG logging and reports

Unless a per-request policy includes and executes a Category Lookup item, Secure Web Gateway (SWG) event logging does not occur and there is no data for reports.

About Safe Search and supported search engines

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.

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

Access and per-request policy comparison

The table summarizes access policy and per-request policy similarities and differences.

Feature Access policy Per-request policy
Configuration tool The visual policy editor. The visual policy editor.
Macros Available in visual policy editor. Not available.
Policy action items Vary by access profile type. Small set of items that are unique to a per-request policy.
Apply Access Policy link Saves the access policy configuration. Not applicable.
Profile Access profile. Not applicable.
Virtual server Specified in the access profile setting. Specified in the per-request policy setting.
Access type support Most. For use in Secure Web Gateway configurations only.
When run At session start. After session is created, on every request.
Policy ending types Allow, Deny, Redirect; endings apply to the session. Allow, Reject; endings apply to URL requests processed in the per-request policy. A Reject ending triggers the Deny ending in the access policy.
Session variables Creates session variables that are available throughout a session. Reads session variables as specified in policy items.
Per-flow variables Not applicable. Creates per-flow variables that are available only while the per-request policy runs.

Category-specific access control example

In this per-request policy example, only recruiters are allowed to access URLs in the job search category. The policy also restricts access to entertainment sites during business hours.

Policy that restricts the Entertainment category to     weekends and the Jobsearch category to recruiters. Category-specific access restrictions

Access for date, time, and user group example

This per-group policy example applies specific URL filters for weekends and weeknights, and restricts access during work hours based on user group.

Policy that restricts access except for weekends, after hours, and sales group Deny or allow access based on date and time and group membership

URL filter per user group example

Each URL Filter Assign item in this per-request policy example should specify a filter that is applicable to the user group.

Group lookup followed by branches for specific groups and a URL filter assignment for each. URL filter based on group membership

SSL intercept and bypass set example

In this example per-request policy, some SSL traffic is bypassed in consideration of the user group or the URL category. Other SSL traffic is rejected or allowed after applying a URL filter.

SSL Bypass for Directors, SSL intercept before category lookup SSL bypass decision based on group membership and URL category
1 On the HTTPS branch after a Protocol Lookup item (not shown), set the SSL bypass action to intercept. Ensuring the SSL bypass action is set to intercept before a category lookup is good practice, particularly if the default SSL bypass action in the client SSL profile is not set to intercept.
2 For directors, do not intercept and inspect any SSL request. The SSL Bypass Set item sets the value of the action to bypass.
3 For others, do not intercept and inspect SSL requests that contain private information. Similarly, the SSL Bypass Set item sets the value of the action to bypass.
4 For SSL requests that do not contain private information, because SSL Intercept Set occurred earlier on the branch, SSL traffic is intercepted. Apply a URL filter to determine whether to allow or reject traffic.

Response Analytics example

In this example per-request policy, after a Category Lookup item obtains a list of categories and a response web page, a Response Analytics item scans the response for malicious embedded content and passes the analysis to the URL filter assign item.

Policy with category lookup, response analytics, and URL filter assign Process of Response Analytics contributing analysis results to URL filter assign

Per-flow variables

Per-flow variables exist only while a per-request policy runs. The table lists per-flow variables and their values.

Name Value
perflow.agent_ending.result 0 (success) or 1 (failure).
perflow.category_lookup.failure 0 (success) or 1 (server failure).
perflow.category_lookup.result.categories Comma-separated list of categories.
perflow.category_lookup.result.customcategory Unique number that identifies a custom category; used internally.
perflow.category_lookup.result.effective_category Name of the category that is ultimately used.
perflow.category_lookup.result.filter_name Name of the URL filter.
perflow.category_lookup.result.hostname Host name retrieved from SSL input.
perflow.category_lookup.result.numcategories Integer. Total number of categories in the comma-separated list of categories.
perflow.category_lookup.result.primarycategory Name of the category that SWG determines is the primary one. (A URL might fit into more than one category, such as news and sports.)
perflow.category_lookup.result.url Requested URL.
perflow.protocol_lookup.result http or https. Defaults to https.
perflow.response_analytics.failure 0 (success) or 1 (server failure).
perflow.session.id Session id.
perflow.ssl_bypass_set 0 (bypass) or 1 (intercept). SSL Bypass Set and SSL Intercept Set items update this value.
perflow.ssl.bypass_default 0 (bypass) or 1 (intercept). Specified in the client SSL profile, used when SSL Bypass Set and SSL Intercept Set items not included in per-request policy.
perflow.swg_scheme_name Scheme name as set in access policy.
perflow.urlfilter_lookup.result.action 0 (reject) or 1 (allow).
perflow.username User name.

Session variables for use in a per-request policy

Per-request policy items that look up the group or class to which a user belongs rely on the access policy to populate these session variables.

Per-request policy item Session variable Access policy item
AD Group Lookup session.ad.last.attr.primaryGroupID AD Query
LDAP Group Lookup session.ldap.last.attr.memberOf LDAP Query
LocalDB Group Lookup session.localdb.groups
Note: This session variable is a default in the expression for LocalDB Group Lookup; any session variable in the expression must match the session variable used in the Local Database action in the access policy.
Local Database
RADIUS Class Lookup session.radius.last.attr.class RADIUS Auth

About per-request policy items

When configuring a per-request policy, a few access policy items are available for inclusion in the policy. Most per-request policy items are unique to a per-request policy.

About Protocol Lookup

A Protocol Lookup item determines whether the protocol of the request is HTTP or HTTPS.

About SSL Intercept Set

In a per-request policy, the SSL Intercept Set item sets the SSL bypass action to Intercept. Including this item early in the policy ensures that SSL traffic is not bypassed until the policy reaches an SSL Bypass Set item.

A default action for SSL bypass (intercept or bypass) is specified in the client SSL profile.

Important: F5 recommends that the SSL forward proxy bypass default action be set to intercept SSL traffic.

The SSL Intercept Set item provides a read-only element, Action, that specifies the Intercept option.

About Category Lookup

A Category Lookup item looks up URL categories for a request and obtains a web response page.

The Category Lookup item provides these elements and options.

Categorization Input
The list specifies these options:
  • Use HTTP URI (cannot be used for SSL Bypass decisions): For HTTP traffic, this option specifies performing a URL-based lookup. When selected, the SafeSearch Mode setting displays.
  • Use SNI in Client Hello (if SNI is not available, use Subject.CN): For HTTPS traffic, this option specifies performing a host-based lookup.
  • Use Subject.CN in Server Cert: For HTTPS traffic, this option specifies performing a host-based lookup.
SafeSearch Mode
The options are Enabled (default) and Disabled. When enabled, SWG enables Safe Search for supported search engines.
Category Lookup Type
Select the category types in which to search for the requested URL. Options are:
  • Select one from Custom categories first, then standard categories if not found
  • Always process full list of both custom and standard categories
  • Process standard categories only
Depending on your selection, the Category Lookup Type 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.
Reset on Failure
When enabled, specifies that SWG send a TCP reset to the client in the event of a server failure.

About Response Analytics

A Response Analytics item inspects a web response page for malicious embedded contents. Response Analytics must be preceded by a Category Lookup item because it obtains a web response page.

Response Analytics provides these elements and options.

Max Buffer Size
Specifies the maximum amount of response data (in bytes) to collect before sending it for content scanning. The system sends the content for analysis when the buffer reaches this size or when the buffer contains all of the response content. Otherwise, the system retains the response data in the buffer.
Max Buffer Time
Specifies the maximum amount of time (in seconds) to retain response data in the buffer. If this time elapses, the system does not send the content for analysis. If the URL is allowed, the system sends the content to the client; otherwise, the system sends a block page or block image to the client.
Exclude Types
Specifies one entry for each type of content to be excluded from content analysis. Images, the All-Images type, do not get analyzed.
Reset on Failure
When enabled, specifies that SWG send a TCP reset to the client in the event of a server failure.

About SSL Bypass Set

The SSL Bypass Set item sets the SSL bypass action to Bypass in a per-request policy. (A default action, intercept or bypass, for SSL bypass is specified in the client SSL profile.)

The SSL Bypass Set item provides a read-only element, Action, that specifies the Bypass option.

About URL Filter Assign

A URL Filter Assign item determines whether to block or allow a request. A Category Lookup item must precede URL Filter Assign to provide categories. The URL Filter Assign item looks up the filter action for each category found for the request. If any filter action is set as Block, the request is blocked. The URL filter item also uses the analysis from the Response Analytics item, if used, to determine whether to block or allow the request.

A URL Filter Assign item provides the URL Filter element, a list of filters from which to select.

Note: A Category Lookup item must precede the URL Filter Assign item.

About Dynamic Date Time

The Dynamic Date Time action enables branching based on the day, date, or time on the server. It provides two default branch rules:

Weekend
Defined as Saturday and Sunday.
Business Hours
Defined as 8:00am to 5:00pm.

The Dynamic Date Time action provides these conditions for defining branch rules.

Time From
Specifies a time of day. The condition is true at or after the specified time.
Time To
Specifies a time of day. This condition is true before or at the specified time.
Date From
Specifies a date. This condition is true at or after the specified date.
Date To
Specifies a date. This condition is true before or at the specified date
Day of Week
Specifies a day. The condition is true for the entire day (local time zone).
Day of Month
Specifies the numeric day of month. This condition is true for this day every month (local time zone).

About AD Group Lookup

An AD Group Lookup item compares a specified string against the session.ad.last.attr.primaryGroupID session variable. The specified string is configurable in a branch rule.

The default simple branch rule expression is User's Primary Group ID is 100. The specified string, 100, should be replaced with a group name specific to the Active Directory configuration at the user site.

Note: An AD Query action is required in the access policy to populate the session variable.

About LDAP Group Lookup

An LDAP Group Lookup item compares a specified string against the session.ldap.last.attr.memberOf session variable. The specified string is configurable in a branch rule. The default simple branch rule expression is User is a member of CN=MY_GROUP, CN=USERS, CN=MY_DOMAIN ; the values MY_GROUP, USERS, MY_DOMAIN, must be replaced with values used in the LDAP group configuration at the user site.

Note: An LDAP Query action is required in the access policy to populate the session variable.

About LocalDB Group Lookup

A per-request policy LocalDB Group Lookup item compares a specified string against a specified session variable.

The string is specified in a branch rule of the LocalDB Group Lookup item. The default simple branch rule expression is User is a member of MY_GROUP. The default advanced rule expression is expression is expr { [mcget {session.localdb.groups}] contains "MY_GROUP" }. In either the simple or the advanced rule, the variable, MY_GROUP, must be replaced with a valid group name.

The session variable must initially be specified and populated by a Local Database action in the access policy. A Local Database action reads groups from a local database instance into a user-specified session variable. It can be session.localdb.groups (used by default in the LocalDB Group Lookup advanced rule expression) or any other name. The same session variable name must be used in the Local Database action and the LocalDB Group Lookup advanced rule expression.

About RADIUS Class Lookup

The RADIUS Class Lookup access policy item compares a user-specified class name against the session.radius.last.attr.class session variable. The specified class name is configurable in a branch rule.

The default simple branch rule expression is RADIUS Class attribute contains MY_CLASS . The variable MY_CLASS must be replaced with the name of an actual class.

Note: A RADIUS Acct or RADIUS Auth action is required in the access policy to populate the session variable.

About per-request policy endings

An ending provides a result for a per-request policy branch. An ending for a per-request policy branch is one of two types.

Allow
Allows the user to continue to the requested URL. Typically, you assign this when the requested URL passes specific checks.
Reject
Blocks the user from continuing to the requested URL. Typically, you assign this when the requested URL fails specific checks. When the per-request policy terminates on a Reject ending, the access policy displays a URL filter denied web page.

Customizing messages for URL filter denied

You need an access profile configured. Before you start, open an access policy for editing.
Customize these messages for display when a user is denied access to a requested URL. When a a per-request policy terminates at a Reject ending, it triggers the access policy Deny ending.
Note: An access policy displays deny messages any time an access policy reaches a Deny ending. You can customize any Deny ending message using this procedure.
  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. Click the Edit Endings button. A popup screen opens.
  4. On the Deny ending that you want to customize, click +Customization to expand the customization settings. The popup screen displays additional setting options.
  5. Customize the text for the URL filter denied settings and for any other settings.
    Option Description
    Language Select the language for which you are configuring Deny messages.
    Session ID Title Specifies the text that precedes the session number when an error occurs.
    Error title Specifies the title for the error message that is displayed when a session cannot be connected.
    Error message Specifies the error message that is displayed when a session cannot be connected.
    New session text Specifies the text that is displayed before the link to start a new session.
    New session link Specifies the link text that is displayed to start a new session.
    Session ID title Specifies the text that precedes the session ID in the Deny message.
    ACL denied page retry link message Specifies the link text that the user can click to retry. This is displayed when a user reaches the ACL denied page.
    URL Filter denied page title Specifies the title for the screen that is displayed when access to a requested URL is blocked.
    URL Filter denied page reject message Specifies the error message that is displayed when access to a requested URL is blocked.
    URL Filter denied page return link message Specifies the link text that the user can click to return to the previous page.
    URL Filter denied page retry link message Specifies the link text that the user can click to retry.
    URL Filter denied page category message Specifies the message to display about the URL category for the blocked URL.
    Access not found page title Specifies the title for the screen that is displayed for access errors.
    Access not found page reject message Specifies the message to display when an access policy is already in progress (in another browser or tab).
  6. Click Save. The popup screen closes.
  7. Click Apply Access Policy to save your configuration.
You customized messages in one language for use with the Deny ending in this access policy.