Manual Chapter :
Session Variables
Applies To:
Show Versions
BIG-IP APM
- 11.4.1, 11.4.0
The rules in an access policy store the values that the actions return in session variables. A session variable contains a number or string that represents a specific piece of information.
You can use the session variable strings in the visual policy editor, to customize a rule for a specific action in an access policy. For more information on configuring access policy rules with session variables, see Assigning variables, and Using advanced access policy rules.
When you use session variables, you typically write them in custom rules, in the Tcl language, or you use them in the variable assign action.
| Table 14.1, Session variables for BIG-IP Access Policy Manager, contains the session variables returned by access policy actions. |
| Table 14.2, Special purpose user session variables, contains special purpose session variables that provide functions in a user session, but are not returned by specific access policy actions. |
| Table 14.3, Network access resource configuration variables and attributes, contains the session variables generated by a network access resource, and the formats of those variables, for use with the variable assign action. |
Note: When using session variables in an access policy configuration, for example, in a logging agent, a session variable might or might not exist depending on the result of the access policy process.
You write rules in Tcl. Although this appendix is not an exhaustive reference for writing and using Tcl expressions, it includes some common operators and syntax rules. Tcl expressions begin with the syntax expr. For more information, see http://www.tcl.tk/man/tcl8.5/TclCmd/expr.htm.
Note: You use iRules® on the BIG-IP® system to provide functionality to the BIG-IP system components. Tcl commands specific to iRules are not available in access policy rules.
You can use Tcl standard operators with most BIG-IP® Access Policy Manager® rules. You can find a full list of these operators in the Tcl online manual, at http://www.tcl.tk/man/tcl8.5/TclCmd/expr.htm.
| - + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators may be applied to string operands, and bit-wise NOT may be applied only to integers. |
| ** Exponentiation. Valid for any numeric operands. |
| * / % Multiply, divide, remainder. None of these operators may be applied to string operands, and remainder may be applied only to integers. The remainder will always have the same sign as the divisor and an absolute value smaller than the divisor. |
| + - Add and subtract. Valid for any numeric operands. |
| << >> Left and right shift. Valid for integer operands only. A right shift always propagates the sign bit. |
| < > <= >= Boolean less than, greater than, less than or equal to, and greater than or equal to. Each operator produces 1 if the condition is true, 0 otherwise. These operators may be applied to strings as well as numeric operands, in which case string comparison is used. |
| == != Boolean equal to and not equal to. Each operator produces a zero/one result. Valid for all operand types. |
| eq ne Boolean string equal to and string not equal to. Each operator produces a zero/one result. The operand types are interpreted only as strings. |
| in ni List containment and negated list containment. Each operator produces a zero/one result and treats its first argument as a string and its second argument as a Tcl list. The in operator indicates whether the first argument is a member of the second argument list; the ni operator inverts the sense of the result. |
| & Bit-wise AND. Valid for integer operands only. |
| ^ Bit-wise exclusive OR. Valid for integer operands only. |
| | Bit-wise OR. Valid for integer operands only. |
| && Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. |
| || Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for boolean and numeric (integers or floating-point) operands only. |
| x?y:z If-then-else, as in C. If x evaluates to non-zero, then the result is the value of y. Otherwise the result is the value of z. The x operand must have a boolean or numeric value. |
A rule operator compares two operands in an expression. In addition to using the Tcl standard operators, you can use the operators listed below.
| contains - Tests if one string contains another string. |
| ends_with - Tests if one string ends with another string. |
| equals - Tests if one string equals another string. |
| matches - Tests if one string matches another string. |
| matches_regex - Tests if one string matches a regular expression. |
| starts_with - Tests if one string starts_with another string. |
| switch - Evaluates one of several scripts, depending on a given value. |
| and - Performs a logical and comparison between two values. |
| not - Performs a logical not action on a value. |
| or - Performs a logical or comparison between two values. |
This table includes session variables and related reference information for each session variable that you can use with Access Policy Manager.
| Active Directory action | Result of the Active Directory query. 0 - Failed 1 - Passed | |||
| Result of the Active Directory authentication attempt. 0 - Failed 1 - Passed | ||||
| Users attributes retrieved during Active Directory query. Each attribute is converted to a separate session variable. | ||||
| session.ad.$name.attr.group. $attr_name | Users group attributes retrieved during Active Directory query. Each group attribute is converted to a separate session variable. | |||
| Result of the LDAP authentication attempt. | ||||
| session.ldap.$name.attr. $attr_name | Users attributes retrieved during AD query. Each attribute is converted to a separate session variable. | |||
| Result of the LDAP query. 0 - Failed 1 - Passed | ||||
| Result of the RADIUS authentication attempt. | ||||
| session.radius.$name.attr. $attr_name | User attributes retrieved during RADIUS authentication. Each attribute is converted to a separate session variable. | |||
| "access_ denied" | The result of the access policy. The result is the ending; for this ending, the result is access_denied. | |||
| Redirect Ending | The result of the access policy. The result is the ending; for this ending, the result is redirect. | |||
| The URL specified in the redirect, for example, "http://www.siterequest.com" | ||||
| The result of the access policy. The result is the ending; for this ending, the result is allowed. | ||||
| session.policy.result.webtop. network_access.autolaunch | The resource that is automatically started for a network access webtop | |||
| Advanced Resource Assign | The assigned dynamic bandwidth control policy | |||
| The assigned static bandwidth control policy | ||||
| 0 - User chooses option 2 on the decision page, which corresponds to the fallback rule branch in the action 1 - User chooses option 1 on the decision page | ||||
| session.windows_check_file. $name.item_0.exist | True - if all files exist on the client. | |||
| session.windows_check_file. $name.item_0.result | Set when files on the client meet the configured attributes. | |||
| session.windows_check_file. $name.item_0.md5 | MD5 value of a checked file. | |||
| session.windows_check_file. $name.item_0.version | The version of a checked file. | |||
| session.windows_check_file. $name.item_0.size | ||||
| session.windows_check_file. $name.item_0.modified | Date the file was modified in UTC form. | |||
| session.windows_check_file. $name.item_0.signer | ||||
| Logon Page (CAPTCHA challenge) | unsigned integer | The unsigned integer is treated as a bitmask. Determines whether to track successful/unsuccessful logon attempts by IP (bit in 0 position) and/or by username (bit in 1 position) when CAPTCHA is enabled. Should not be used by external modules because it is intended for very specific purposes. | ||
| Machine Cert Auth | 0 - Neither certificate nor private key were found. 1 - Both certificate and private key were found. 2 - Certificate was found, but private key was not found. Nothing received from client. Data received is not in correct format. Linux client is trying to access the agent; (Machine Cert Auth is not supported on Linux) Incorrect configuration. For example if CA profile is not configured. | |||
| Generated one-time password value to send to the end user. Example message: One-Time Passcode: %{session.otp.assigned.val} | ||||
| Internally used timestamp; OTP expiration in seconds since this date and time: (00:00:00 UTC, January 1, 1970) | ||||
| OTP time-to-live; configurable as OTP timeout in seconds. Example message: OTP expires after use or in %{session.otp.assigned.ttl} seconds | ||||
| Result of OTP authentication attempt: | ||||
| session.windows_check_process. $name.result | ||||
| Windows Registry check | session.windows_check_registrys. $name.result | |||
| session.windows_info_os.$name. ie_version | Stores the Internet Explorer version | |||
| session.windows_info_os.$name. ie_updates | "SP2KB12345KB54321" | A list of installed SP and KB fixes for Internet Explorer | ||
| session.windows_info_os.$name. platform | Win2003 - Windows 2003 Server | |||
| "SP2KB12345KB54321" | A list of installed SP and KB fixes for Windows | |||
| List of current windows user names | ||||
| Resource allocation | "resourcename1 resourcename2" | A space-delimited list of assigned resources. | ||
| The name of the assigned webtop. | ||||
| Client certificate authentication | ||||
| Certificate Result (OK or error string) | ||||
| 0 - certificate does not exist 1- certificate exists | ||||
| Session management | The UI mode, as determined by HTTP headers. | |||
| The language in use in the session. | ||||
| The character set used in the session. | ||||
| portalclient "Standalone" | The client type as determined by HTTP headers. | |||
| Session management | ||||
| The client platform as determined by HTTP headers. | ||||
| Enables direct access to a resource from the webtop. Used with Citrix resources. See Using the session.user.access_mode session variable. |
The session.user.access_mode session variable allows users to be assigned a full webtop for publishing resources with direct access to the resources, without an Access Policy Manager resource assigned. This is designed to simplify access to internal resources for local users.
| local - enables local access mode |
| Any other value - disables local access mode. This access mode is disabled in a session by default. |
| 1. | In the Visual Policy Editor, on an access policy branch, add a Variable Assign agent with the custom expression |
| 2. | Assign a Citrix resource and full webtop on the same access policy branch. The resource connection is made directly to the Citrix server. |
Use the following session variables with the variable assign action to customize the behavior of a user session.
| A space-delimited list of assigned ACLs. This variable is created to store the list of ACLs. To modify the list of ACLs with the variable assign action or an advanced access policy rule, modify the previous session variable, session.assigned.acls. | |||
| xxx.xxx.xxx.xxx For example, 192.168.12.10 | The informational variable that stores the client IP address assigned by Access Policy Manager after the access policy completes. | ||
| An informational variable that stores the reason the session was terminated. | |||
| A space-delimited list of assigned resource names. This list is generated based on the list of assigned resource groups. | |||
| The route domain ID number assigned to the client session. | |||
| string (8 hex characters)( | The ID for a session. For example, e2d0b683. | ||
| You can use the session user name variable with the variable assign action to replace the user name value that is passed to an authentication action in the access policy. An authentication action then authenticates with this user name value. | |||
| The session password variable contains the user password that is collected in the logon page action. This variable stores the password, then sends it to the authentication server. You should not configure the variable assign action to replace this variable. |
This table includes the variables you can access in a network access resource, and the formats and values of the variable attributes.
Use this table with the variable assign action, to correctly format the replacement attribute for an existing network access resource configuration variable.
When the session variable requires that you write replacement XML in a specific format, the XML is presented in this table as <tag>tagdata</tag>. In this example, you type both the opening <tag> and the closing </tag> elements as provided, then type the actual XML data between the opening and closing elements. For example, the following is an entry in the table.
Important: The result of an evaluated expression or custom expression that you use to replace a network access property must provide a value in the format described in the Attribute value format column.
| The attribute value is the name of a leasepool that exists on Access Policy Manager | ||
| The attribute value is the name of an SNAT pool. The SNAT pool must be configured on the Access Policy Manager. | ||
| 0 = disable compression 1 = enable compression | ||
| < client_proxy_settings > <client_proxy>1</client_proxy> <client_proxy_script>proxy_script </client_proxy_script> <client_proxy_address>proxyaddress </ client_proxy_address> <client_proxy_port>proxyport</client_proxy_port> <client_proxy_local_bypass>1 </client_proxy_local_bypass> <client_proxy_exclusion_list> <item>exclusion_list_item1</item> <item>exclusion_list_item2</item> </client_proxy_exclusion_list> </client_proxy_settings> Note that <client_proxy> should have the value 1 for the other settings to be effective, otherwise all other setting from <client_proxy_settings> will be ignored. | ||
| <drive_mapping> <item> <description> description</description> <path>drive_path</path> <drive>drive_letter</drive> </item> </drive_mapping> | ||
| The attribute value is the session update threshold, in seconds. | ||
| <address_space_include_dns_name> <item><dnsname> dnsname1 </dnsname></item> <item><dnsname> dnsname2 </dnsname></item> </address_space_include_dns_name> | ||
| The attribute value is a space-separated list of subnets. For example: 192.168.30.0/255.255.255.0 172.30.11.0/255.255.255.0 | ||
| The attribute value is a space-separated list of subnets. For example: 192.168.30.0/255.255.255.0 172.30.11.0/255.255.255.0 | ||
| 0 = disable address space DHCP request exclusion 1 = enable address space DHCP request exclusion | ||
| address_space_exclude_subnet = "" address_space_include_subnet = "128.0.0.0/128.0.0.0 0.0.0.0/128.0.0.0" address_space_include_dns_name = "*" | ||
| The DNS Default Domain Suffix. For example, siterequest.com. | ||
| The number for the client interface speed value in the network access resource, in bytes. | ||
| 0 = disable the File and printer sharing for Microsoft Networks option 1 = enable the File and printer sharing for Microsoft Networks option | ||
| <application_launch> <item> <path>path</path> <parameter>string</parameter> <os_type>os_type</os_type> </item> </application_launch> For the <os_type> value, type WINDOWS, MAC, or IOS. This field is case sensitive. | ||
| Note: setting this to any number other than 0 enables DTLS in the network access resource, and sets the number you specify as the DTLS port. |
With BIG-IP® Access Policy Manager® Configuration utility, for many configuration fields, you can use a session variable to retrieve data from the session that populates a field at session runtime.
| Not all fields support session variables. See Supported fields for session variables in the Configuration utility for supported fields and configuration information. |
| Any field that supports session variables can support multiple session variables. For example, you can create a URL in a field from session variables. |
| Use session.logon.protocol to specify the protocol for the URL. |
| Use session.network.name to specify the host address portion of the URL. |
| Use session.start.path to specify the path info that follows the host address. |
The Redirect URL field appears when you add or edit an ending in the visual policy editor. You use session variables in this field to dynamically generate the Redirect URL for the client.
In this example, when the user reaches a redirect ending in the access policy, the access policy creates the Redirect URI dynamically from the current LDAP session.
Note: Currently the Redirect URL field only supports session variables for the host and path, and not for scheme.
Figure 14.5 LDAP session variables in Redirect URL field
The Start URI field for a portal access webtop appears when you create a webtop for portal access only. You use session variables in this field to dynamically generate the webtop URL for the client.
In this example, when the user reaches the portal access webtop, the web application starts at the URI that the access policy dynamically generates based on variables from the current LDAP session.
There are several fields you can configure with session variables in the Form-based SSO creation page:
| Username Source field in the Credentials Source area (by default populated with session.sso.token.last.username) |
| Password Source field in the Credentials Source area (by default populated with session.sso.token.last.password) |
| Start URI field in the SSO Method Configuration area |
| Form Action field in the SSO Method Configuration area |
| Form Parameter for User Name field in the SSO Method Configuration area |
| Form Parameter for Password field in the SSO Method Configuration area |
| Hidden Form Parameters/Values field in the SSO Method Configuration area |
| Successful Logon Detection Match Value field in the SSO Method Configuration area |
In this example, SSO information to maintain the user session is determined at runtime by SSO session variables. The following session variables are used to populate the SSO form.
Figure 14.9 SSO session variables for SSO fields
There are several fields you can configure with session variables on the NTLM SSO creation page:
| Username Source field in the Credentials Source area (by default populated with session.sso.token.last.username) |
| Password Source field in the Credentials Source area (by default populated with session.sso.token.last.password) |
| Domain Source field in the Credentials Source area (by default populated with session.logon.last.domain) |
| NTLM Domain field in the SSO Method Configuration area |
In this example, SSO information to establish the user session is determined at runtime by SSO session variables. The following session variables are used to populate the SSO form.
Figure 14.11 SSO session variables for NTLM fields
There are two fields automatically configured with session variables in the HTTP Basic SSO creation page:
| Username Source field in the Credentials Source area (by default populated with session.sso.token.last.username) |
| Password Source field in the Credentials Source area (by default populated with session.sso.token.last.password) |
In this example, SSO information to establish the user session is determined at runtime by SSO session variables. The following session variables are automatically populated in the SSO form.
Figure 14.13 SSO session variables for HTTP Basic SSO fields
There are two fields automatically configured with session variables in the Kerberos SSO creation page:
| Username Source field in the Credentials Source area (by default populated with session.sso.token.last.username) |
| Password Source field in the Credentials Source area (by default populated with session.sso.token.last.password) |
In this example, SSO information to establish the user session is determined at runtime by SSO session variables. The following session variables are automatically populated in the SSO form.
Figure 14.15 SSO session variables for Kerberos SSO fields
You can use session variables to specify SSO header name-value pairs. To set name-value pairs, you must select Advanced on any SSO configuration page.
In this example, SSO header insertion name-value pairs can be determined at runtime with session variables. Use custom session variables to populate these fields in the SSO form. The following session variables are examples only.
You can use a session variable for the LDAP Query SearchFilter parameter in the visual policy editor, to specify search parameters.
In this example, the SearchFilter field is populated with the username from the current session.
Figure 14.19 SearchFilter session variable for LDAP Query
You can use a session variable for the AD Query SearchFilter parameter in the visual policy editor, to specify search parameters.
In this example, the SearchFilter field is populated with the Subject Alternative Name from the current Active Directory session.
You can use a session variable in the AAA Server configuration Hidden Form Parameters/Values field, to specify hidden form parameters for AAA server form-based authentication.
In this example, the Hidden Form Parameters/Values field is populated with a hidden form submission command that submits the username associated with the session.
You can use session variable fields in the Network Access configuration, to specify the caption and detailed description for a network access resource that appears on the full webtop.
In this example, the Caption and Detailed Description fields are populated with custom session variables, which are defined in the Variable Assign action for the access policy.
You can use session variable fields in the Network Access Launch Applications configuration, to specify the application path and application parameters for the auto launch applications for a network access resource.
In this example, the Application Path and Parameters fields are populated with custom session variables, that are defined in the Variable Assign action for the access policy.
You can use a session variable in the Network Access Drive Mapping configuration, to specify the network path for the drive mapping for a network access resource.
In this example, the Path field is populated with the result from a custom session variable, which is defined in the Variable Assign action for the access policy.
Figure 14.29 Network access drive mapping path session variable
You can use session variables in the Application Tunnel configuration, to specify the destination, application path, and application parameters.
In this example, the Destination field, Application Path, and Parameters fields are populated with the result from custom session variables, which are defined in the Variable Assign action for the access policy.
Figure 14.31 Application tunnel session variables
You can use session variables in the remote desktop configuration, to specify the destination, username source, password source, and domain source.
In this example, the Destination, Username Source, Password Source, and Domain Source fields are populated with the result from a custom session variable, which is defined in the Variable Assign action for the access policy, and the username, password, and domain are automatically populated with variables from the session.
Figure 14.33 Remote desktop resource session variables
