F5 Tech Focus
FirePass Guide to Session Variables
The session variable feature enables F5 FirePass® administrators
to configure text fields of user favorites enabling resources to be
dynamically assigned. This paper discusses session variables in FirePass.
by Pete Silva
Technical Marketing Manager
F5 Tech Focus
FirePass Guide to Session Variables
Contents
Introduction 3
Session Variables in FirePass 3
Specifications 3
Session Variables in FirePass Configuration 6
Session Variable-based Group Mapping 6
Session Variables Defined During Group Mapping and Authentication 8
Session Variable-based Intranet WebTop 16
Use of Session Variables for Network Access 19
Session Variables-Based Protected Resource Configuration 20
Additional Session Variables for Favorites 20
Troubleshooting Session Variables 21
Conclusion 21
2
F5 Tech Focus
FirePass Guide to Session Variables
Introduction
Hypertext Transport Protocol (HTTP) is a stateless protocol, meaning it does not
keep track of users or what those users requested from a web application. While
a simple cookie can help keep track of this information, adding session variables
make it possible to store and post information about the client throughout the
entire web application visit or session. The result is that each session is essentially
its own object and is preserved during a specific period, or until the session is
closed. Session variables enable you to store information, such as the logon_ID,
of each unique visitor and use it in other areas of the application. Based on that
session variable, you can provide specific user customization.
The session variable feature enables FirePass administrators to configure text
fields of user favorites. The values of the predefined strings are determined during
a user session, and enable administrators to configure user favorites based on
distinctive user properties.
NOTE: Examples shown use FirePass v6.02
Session Variables in FirePass
FirePass session variables consist of two main sets:
1. S
ession variables defined during pre-logon sequence. These variables
are defined by the end-point security module while executing pre-logon
sequence. These variables contain information about the end client.
2. S
ession variables defined during group mapping and user’s
authentication. FirePass converts user’s attributes received from external
group, mapping servers and authentication servers to session variables.
A complete list of these variables is available at online help: In the administrative
GUI, click Users: End Point Security: Pre-Logon Sequence.
Specifications
Format
A variable is a string enclosed inside % symbols and contains no white space. A
session variable is a variable which begins with “%session.” and ends with “%”.
3
F5 Tech Focus
FirePass Guide to Session Variables
1. S ingle or multiple occurrences of session variables will be replaced with
their user-session values.
2. F ive session variables are available for all text fields that support session
variables:
%session.user.username%
%session.user.firstname%
%session.user.lastname%
%session.user.fullname%
%session.group.name%
NOTE: Some places support five special variable shortcuts (as part of URL
variables) before implementation: %group%, %username%, %firstname%,
%lastname%, %fullname%. Additionally, %password% is also supported in
some places. There is no change to the areas that already support the six special
global variable shortcuts.
IMPORTANT: Any variable that is not a session variable is not replaced.
For example, given:
%session.ssl.cert.cn% = John Doe
%session.user.username% = jdoe
Then during a user session, a session variable predefined as “AppTunnel favorite for
%session.ssl.cert.cn% (%session.user.username%) %aa.bb.cc%” will be seen as:
“AppTunnel favorite for John Doe (jdoe) %aa.bb.cc%” if certificate is
presented
“AppTunnel favorite for (jdoe) %aa.bb.cc%” if certificate is not presented
Administrator User Interface
A percent-sign icon (%) is placed to the right of each session variable-supported
input text box. The tooltip will say “You can specify session variables in this field”
when mouse pointer hovers over the icon. The icon is clickable. Clicking it will
open a new Help page that describes general usage of session variables. Session
variables are supported in most of the fields in the resource configuration area.
NOTE: The examples shown throughout this paper address many typical
situations, but do not cover all scenarios offered on FirePass with session variables.
On the admin console, you can plug session variables into text fields in the
supported areas listed below.
4
F5 Tech Focus
FirePass Guide to Session Variables
Network Access
* Resources
Under Client Settings tab, option “Assign IP address using session variables
(2nd Priority),” a text field to accept the designated session variable, and all
other tabs and options,
Excluding client proxy settings, IP Address Mapping Table under Client
Settings tab, and IP Group Filters tab.
* Master Group Settings
* Excluding global settings, client downloads
Application Access
* App Tunnels
* Legacy Hosts
* Terminal Servers
* Excluding Global Settings
Portal Access
* Web Applications
Resources
* Master Group Settings
Intranet Webtops
Proxies
Excluding Content Processing, Caching, and Compression
* Windows Files
Excluding Mobile Email, Content Inspection
5
F5 Tech Focus
FirePass Guide to Session Variables
Logging and Debugging
If any variable is not converted as anticipated during a user session, the variable
is either discarded or used as a pure string in the intended field. See the Format
section for conversion rules.
Please see Device Management: Maintenance: Troubleshooting Tools: Session
Variable Dump to view a user’s session variables as part of Logon Reports. This
area aids in determining which variables can be used within supported fields.
Session Variables in FirePass
Configuration
Following description applies to all session variables (pre-logon as well as user’s
attribute based session variables):
NOTE: When you want to use a session variable in FirePass configuration (including
the session variable-based group-mapping configuration), enclose the name of session
variable using %...%. In FirePass, this indicates that the value is a session variable.
See the examples below. All places have session variable names quoted with %...%.
Session Variable-based Group Mapping
Use session variables to dynamically map users to the appropriate master and
resource group when they log on to the FirePass controller. You can use the
following types of session variables for dynamic group mapping:
• Session variables defined during the pre-logon sequence.
• S ession variables defined from external attributes that are received from
the external group mapping servers (Active Directory and LDAP servers
only) during dynamic group mapping. Attributes received from servers are
converted to session variables.
• Custom session variables defined during the pre-logon check.
Because they are defined after the FirePass controller performs group mapping,
you cannot use following types of session variables for group mapping:
• Session variables defined during post-logon sequence
• S ession variables defined from external attributes that are received from
external authentication servers during user authentication
6
F5 Tech Focus
FirePass Guide to Session Variables
Example 1: Following screenshot shows two entries in the master group mapping table
that direct users to different master groups based on their user-agent settings. This is used
to direct users of Mozilla and Internet Explorer browsers to different master groups.
A typical usage scenario could be directing the client to different master groups.
This can be done based on their user agent.
Example 2: The following screenshot shows the use of session variables for
dynamic resource group mapping. The administrator wants to assign different
resource groups to users running different operating systems to make sure they
get the appropriate applications. This example illustrates how Windows XP and
MacOS users gain access to different resource groups.
7
F5 Tech Focus
FirePass Guide to Session Variables
Session Variables Defined During Group Mapping
and Authentication
FirePass retrieves a user’s attributes from the external group mapping servers during
dynamic group mapping. These attributes are then converted to session variables.
Currently only LDAP and Active Directory (AD) servers are supported. That means
that attributes received from only the LDAP server and AD server are converted to
session variables. As of this publication, attributes received from external RADIUS
server are not converted to session variables.
Active Directory Session Variables
Session variables based on attributes received from the external AD server are
named based on following notation: session.ad.groupmapping.attribute_name =
attribute_value
If the attribute is a multi-value attribute, FirePass forms a space-separate string
containing all values and uses it as the attribute_value.
session.ad.groupmapping.attribute_name = “attribute_value1 attribute_value2…”
The following grid shows Active Directory session variables that you can use with
dynamic group mapping:
Variable Description
session.ad.groupmapping.attribute_ An Active Directory session variable
name=attribute_value” whose attribute returns a single value.
session.ad.groupmapping.attribute_ An Active Directory session variable
name=”attribute_value1 attribute_value2 . . .” whose attribute returns a multiple values.
Following screenshot shows a list of attributes received from the AD server
that are then converted to session variables for the user. You can see all session
variables for a specific user in their LogOn Reports on FirePass under Device
Management: Reports: LogOn.
8
F5 Tech Focus
FirePass Guide to Session Variables
LDAP Session Variables
Session variables based on attributes received from external LDAP server are
named based on the following notation: session.ldap.groupmapping.attribute_
name=attribute_value.
Like AD, if the attribute is a multi-value attribute, FirePass forms a space-separate
string containing all values and uses it as the attribute_value. For example,
session.ldap.groupmapping.attribute_name=“attribute_value1 attribute_value2…”
The following grid shows LDAP session variables that you can use with dynamic
group mapping:
Variable Description
session.ldap.groupmapping.attribute_ An LDAP session variable whose attribute
name=attribute_value returns a single value.
session.ldap.groupmapping.attribute_ An LDAP session variable whose attribute
name=”attribute_value1 attribute_value2 . . .” returns multiple values.
Following screenshot shows a list of attributes received from LDAP server and
then converted to session variables for a user.
9
F5 Tech Focus
FirePass Guide to Session Variables
To configure dynamic group mapping based on a session variable:
1. In the navigation pane, click Users, expand Groups, and click Dynamic
Group Mapping.
2. Click the Group mapping methods tab.
3. From the Add Mapping Method list, select the Session Variable method.
lick the Master group mapping table tab.
4. C
The screen displays the Master Group Mapping table.
5. F rom the Mapping Method list, select Session Variable and click the
Add button to map the session variable to the master group. The screen
refreshes to display the Map Session Variable to FirePass group table.
6. In the Session Variable column, specify the session variable you want to
use for the master group.
7. T o enables users to log on to a specific master group based on the values
returned by the session variable, and configure one of the following options:
• If you want to use the default value(s) returned by the session
variable, check Map verbatim option. The default is unchecked.
• In the Value column, type the value that you want the session
variable to return. For example:
10
F5 Tech Focus
FirePass Guide to Session Variables
8. In FirePass Group, select a master group that you want associated with
the session variable and then click the Add button. The system saves the
mapping entry and enables users to log on to a specific master group.
IMPORTANT: You must enclose a session variable within %...% percent symbol.
lick the Resource group mapping table tab and select the Mapping
9. C
Method, Session variable, and click the Add button. The system saves
the mapping entry and allows users to log on through a specific virtual host
to a specific resource group.
10. To allow users access to the resources in a specific resource group based on the
values returned by the session variable, configure one of the following options:
• If you want to use the default value (s) returned by the session
variable, check Map verbatim option. The default is unchecked.
• In the Value column, type the value that you want the session
variable to return. For example:
11. F rom the FirePass Group list, select the resource group that you want associated
with the session variable and click the Add button. The system saves the mapping
entry and enables user access to the resources in a specific resource group.
11
F5 Tech Focus
FirePass Guide to Session Variables
Session Variables Defined During User Authentication
FirePass retrieves user attributes from external authentication servers during user
authentication. These attributes are then converted to session variables.
Currently only LDAP and AD servers are supported, so attributes received from only
LDAP server and AD server are converted to session variables. Currently, attributes
received from external RADIUS server are not converted to session variables.
Session Variable Based on Attributes Received from External AD Server
During User Authentication
These variables are named based on following notation: session.ad.auth.
attribute_name = attribute_value
Again here, if the attribute is a multi-value attribute, FirePass forms a space separate
string containing all values and uses it as the attribute_value: session.ad.auth.
attribute_name=“attribute_value1 attribute_value2…”
The following screenshot shows a list of attributes received from AD server and
then converted to session variables for a test user:
12
F5 Tech Focus
FirePass Guide to Session Variables
Session Variables Based on Attributes Received from External LDAP
Server During User’s Authentication
These variables are named based on following notation:
session.ldap.auth.attribute_name = attribute_value
As with the others, if the attribute is a multi-value attribute, FirePass forms a
space-separate string containing all values and uses it as the attribute_value:
session.ldap.auth.attribute_name = “attribute_value1 attribute_value2…”
The following screenshot shows a list of attributes received from the LDAP server
and then converted to session variables for a test user:
User-Defined Session Variable Settings
Use the option Display extra input field at logon for user defined session
variable when you want to enable users to specify a value at the logon page.
When you enable this feature, the FirePass controller presents the user with a field
in which to type text at the logon page. This field is then converted to a session
variable named: %session.userdef.logon_extra_field%.
For instance, you can use this session variable to enable users to access different
master groups. In the following example, you use the %session.userdef.logon_
extra_field% to configure a master mapping table to direct the users to specific
master groups based on what they type in the input field.
13
F5 Tech Focus
FirePass Guide to Session Variables
To authenticate a user from a list of master groups:
1. In the navigation pane, click Users and then click Global Settings.
2. In the Master Group Selection area, check the option Display extra input
field at logon for user defined session variable check box and click the
Update button. The screen refreshes and the session variable prompt appears.
3. T o instruct the user on how to select a master group, type the text that you
want displayed to the user in the User defined session variable prompt
box (for example, type your organization). This text is displayed at the users’
logon page.
4. In the navigation pane, click Users, expand Master groups, and click
Dynamic Group Mapping.
lick the Master Group Mapping table tab, and configure a Session
5. C
Variable mapping method.
Use the %session.userdef.logon_extra_field% session variable to
dynamically map users to the appropriate master when they log on to the
FirePass controller. For information about how to use session variables, refer
to the online help on this screen.
6. F rom the Mapping Method list, select Session Variable and click the
Add button to map the session variable to the master group. The screen
refreshes to display the Map Session Variable to FirePass group table.
7. In the Session Variable column, specify the session variable you want to use
for the master group.
8. T o enables users to log on to a specific master group based on the values
returned by the session variable and configure one of the following options:
• If you want to use the default value(s) returned by the session
variable, check the Map verbatim option. The default is unchecked.
• In the Value column, type the value that you want the session
variable to return. For example:
14
F5 Tech Focus
FirePass Guide to Session Variables
9. In the FirePass Group, select a master group that you want to associate with
the session variable and then click the Add button.
IMPORTANT: You must enclose a session variable within %...% percent symbol
The system saves the mapping entry and enables users to log on to a specific
master group through a specific session variable.
10. Click the Resource group mapping table tab and select the Mapping
Method, Session variable, and click the Add button. The system saves
the mapping entry and allows users to log on to a specific resource group
through a specific session variable.
11. To enables users to access the resources in a specific resource group based
on the values returned by the session variable, and configure one of the
following options:
• If you want to use the default value(s) returned by the session
variable, check Map verbatim option. The default is unchecked.
• In the Value column, type the value that you want the session
variable to return. For example:
15
F5 Tech Focus
FirePass Guide to Session Variables
12. From the FirePass Group list, select the resource group that you want
associated with the session variable and click the Add button.
The system saves the mapping entry and enables users to access the resources in
a specific resource group.
13. Click the Save button.
Session Variable-based
Intranet WebTop
You can direct different users to different intranet WebTops based on session variables.
In this scenario, for example, an administrator wants to direct different users to
different WebTops based on the landing URL used to log in to FirePass. It can be
done in following manner:
Step 1: Admin defines the intranet WebTop URL setting in terms of session
variables for different master groups.
The WebTop is configured in terms of a custom session variable:
%session.userdef.my-dynamic-webtop%
16
F5 Tech Focus
FirePass Guide to Session Variables
Next, the admin creates a pre-logon sequence to initialize this custom variable to
appropriate values based on landing URL information. The following screen shot
shows the pre-logon sequence:
This pre-logon sequence has three rules: CNN, Yahoo, and fallback. These rules
are checking for the landing URL value. Let’s see the content of CNN rule:
If CNN rules matches, then CNNWebTop action is executed. This action defines
custom variable “my-dynamic-webtop” to “http://www.cnn.com/.”
17
F5 Tech Focus
FirePass Guide to Session Variables
Thus if a user uses CNN landing URL to access FirePass, this variable is initialized to
the value “http://www.cnn.com/.”
Once the user successfully authenticates, they are directed to appropriate WebTop after
the login; in this case, the WebTop evaluates to http://www.cnn.com in this case.
Similarly if a user uses Yahoo as the landing URL, the custom variable is set to
http://www.yahoo.com in the action “YahooWebTop.” And consequently user is
directed to http://www.yahoo.com.
18
F5 Tech Focus
FirePass Guide to Session Variables
IMPORTANT POINTS:
1. If a user doesn’t use any landing URL, admin needs to define a fallback
action, this MUST cause the custom variable to be initialized to value
“default.” This causes FirePass to present default FirePass WebTop after login.
2. Y
ou can only use session variables for URL field in the intranet WebTop
configuration. Session variables for URL variables are not yet supported.
Use of Session Variables for
Network Access
Administrators can use the attribute values for configuring network access favorite by
specifying the corresponding session variable as the value of a LAN address space.
For example following screenshot shows how LAN address space is configured
in network access using an LDAP attribute “SubnetAddress,” which is retrieved
during user authentication.
The value of the LAN address space is evaluated by substituting the value of the
“SubNetAddress” LDAP attribute received during the user’s authentication. This
way the administrator can control the user’s access subnet through LDAP attributes.
19
F5 Tech Focus
FirePass Guide to Session Variables
Session Variables-Based Protected Resource Configuration
The attributes-based session variables can be used in the rules for protected
resource configuration. This is an extension of the already existing protected
resource configuration functionality, which enables an administrator to create
custom rules based on session variables.
An administrator can use the session variables corresponding to the various attributes to
configure various rules, which then can be used for protected resource configuration.
Additional Session Variables for Favorites
You can specify the following session variables in favorites. These session variables
are only available after the user logs on to the FirePass controller.
Note: You cannot use these variables with dynamic group mapping or pre-logon
sequences.
Variable Type Description
session.user.username string User’s logon name
session.user.firstname string User’s first name
session.user.lastname string User’s last name
session.user.fullname string User’s full name
session.group.name string User’s master group name
20
F5 Tech Focus
FirePass Guide to Session Variables
Troubleshooting Session Variables
The administrator can enable “Session Variable Dump” under Device Management:
Maintenance: Troubleshooting page.
If enabled, this will cause all session variables for a specific user’s session to be
stored in the log-on report for that user. Administrators can then take a look at all
session variables defined for a user during a specific session.
Conclusion
FirePass session variables provide the administrator the power and ease of using a
single variable to detect, authenticate, authorize, and provide resources to the user.
Session Variables can streamline the administration and management of FirePass.
The session values are determined when a user logs on, and enable administrators
to configure user favorites based on distinctive user properties, and ensure that
authenticated users get exactly what they are authorized to view.
21
F5 Tech Focus
FirePass Guide to Session Variables
F5 Networks, Inc. F5 Networks F5 Networks Ltd. F5 Networks
Corporate Headquarters Asia-Pacific Europe/Middle-East/Africa Japan K.K.
401 Elliott Avenue West +65-6533-6103 Phone +44 (0) 1932 582 000 Phone +81-3-5114-3200 Phone
Seattle, WA 98119 +65-6533-6106 Fax +44 (0) 1932 582 001 Fax +81-3-5114-3201 Fax
+1-206-272-5555 Phone
[email protected] [email protected] [email protected](888) 88BIGIP Toll-free
+1-206-272-5556 Fax
www.f5.com
[email protected]TF-FIREPASS-guide-to-session-variables 08/08
© 2008 F5 Networks, Inc. All rights reserved. F5, F5 Networks, the F5 logo, BIG-IP, VIPRION, FirePass, and iControl are trademarks or registered trademarks of F5 Networks, Inc. in the U.S.
and in certain other countries. 22
