Managing User-Agent Mappings
Web browsers include a User-Agent header in Web requests to identify themselves to servers. Servers use the User-Agent header in a request to return a response that is suited to the Web browser that sent the request. Microsoft® Internet Security and Acceleration (ISA) Server 2006 uses the User-Agent header in Web requests to ascertain whether forms-based authentication can be performed and to determine the specific form that should be provided for forms-based authentication. To do this, ISA Server maintains an ordered list of mappings of User-Agent headers to a type of authentication for each ISA Server array. The User-Agent mappings that are defined and enabled in an array are rule elements that apply to all Web publishing rules defined in the array that use one of the following authentication schemes for forms-based authentication.
Authentication scheme | Description |
---|---|
FBA with AD |
Enables forms-based authentication of domain users using the Active Directory® directory service. |
FBA with LDAP |
Enables forms-based authentication of domain users using the Lightweight Directory Access Protocol (LDAP) to communicate with a domain controller (an LDAP server). |
FBA with RADIUS |
Enables forms-based authentication using the Remote Authentication Dial-In User Service (RADIUS) to communicate with a RADIUS server. |
ISA Server uses these User-Agent mappings to determine the type of form to provide to a client based on the User-Agent header provided by the client. Each User-Agent mapping in the list can be enabled or disabled.
The User-Agent headers to which a User-Agent mapping applies are specified by a string. This string may contain wildcard characters (*). When this string contains only a wildcard character (*), the User-Agent mapping applies to all User-Agent headers. When this string begins and ends with a wildcard character, the User-Agent mapping applies to any User-Agent header that contains the substring between the wildcard characters.
The types of authentication that are supported in User-Agent mappings include forms-based authentication using forms written in specific formats and Basic authentication. ISA Server supports forms for forms-based authentication that are written in the following formats:
- HTML 4.01. Intended for standard browsers.
- cHTML. Intended for browsers that support cHTML, such as i-mode mobile devices.
- XHTML-MP. Intended for browsers that support xhtml-mp, such as Microsoft Windows Mobile® and other mobile devices.
These forms are stored in the HTML, CHTML, and XHTML folders, which are located in the ISA Server Installation Directory\CookieAuthTemplates\ISA folder, and may be customized.
The following User-Agent mappings are supplied with ISA Server.
No. | User-Agent headers | Authentication type |
---|---|---|
1 |
*Blazer* |
XHTML-MP forms |
2 |
*DoCoMo* |
cHTML forms |
3 |
*Windows CE* |
XHTML-MP forms |
4 |
*Symbain OS* |
XHTML-MP forms |
5 |
*SonyEricsson* |
XHTML-MP forms |
6 |
*Frontpage* |
Basic authentication |
7 |
*Mozilla* |
HTML 4.01 forms |
8 |
*Opera* |
HTML 4.01 forms |
9 |
*MSRPC* |
Basic authentication |
10 |
* |
Basic authentication |
When ISA Server needs to authenticate a client, including a mobile client, in a Web publishing scenario and the Web listener is configured to use the FBA with AD, FBA with LDAP, or FBA with RADIUS authentication scheme, ISA Server reads the User-Agent header in the Hypertext Transfer Protocol (HTTP) GET request. ISA Server then finds the first User-Agent mapping defined in the list that matches the User-Agent header. Note that the last User-Agent mapping in the list is a default mapping that specifies Basic authentication as a fallback authentication method.
ISA Server uses the authentication type in the applicable mapping to determine the response. If the authentication type is Basic authentication, the response consists of a WWW-Authenticate: Basic header, and the HTTP status code is set to 401. Otherwise, a 302 response that redirects the client to the applicable form is sent. In particular, when a GET request is sent from a mobile device that includes the string Windows CE in the User-Agent header, ISA Server sends back a 302 response that redirects the client to the XHTML-MP form. When a GET request is sent from Microsoft Internet Explorer®, ISA Server finds the string Mozilla in the User-Agent header and sends back a 302 response that redirects the client to the HTML 4.01 form.
A single User-Agent mapping is defined by an FPCUserAgentMapping ISA Server administration COM object, and all the User-Agent mappings defined in an ISA Server array are contained in the FPCUserAgentMappings collection for the array. The FPCUserAgentMappings collection is accessed through the UserAgentMappings property of the FPCRuleElements object.
The FPCUserAgentMapping object provides the following properties for defining a User-Agent mapping:
- UserAgent. This property gets or sets the string that specifies the User-Agent headers to which the mapping applies.
- FBAFormsType. This property gets or sets a value from the FpcFBAFormsTypes enumerated type that specifies the type of authentication that will be associated with the User-Agent headers specified in the mapping.
- Order. This property gets an integer that specifies the position of the User-Agent mapping in the list of User-Agent mappings, which corresponds to the order in which the User-Agent mappings are tested to find a mapping that matches the User-Agent header in a request.
- Enabled. This property gets or sets a Boolean value that indicates whether the User-Agent mapping is enabled.
Note
The properties and methods of the FPCUserAgentMappings collection and its elements cannot be accessed through ISA Server Management.
On this page
Listing User-Agent mappings
Creating a new User-Agent mapping
Editing or deleting a User-Agent mapping
Listing User-Agent mappings
The Microsoft Visual Basic® Scripting Edition (VBScript) code in ListUserAgentMappings.vbs (listed later in this document) retrieves the collection of User-Agent mappings defined in an ISA Server array and displays the User-Agent header, the type of authentication specified, and an indication of whether the mapping is enabled for each User-Agent mapping in the collection. This script, as presented, must be run on an ISA Server 2006 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
To use this script, paste the code in the script listing into a text editor, save it in a file named ListUserAgentMappings.vbs, and run it from a command prompt.
Usage:
CScript ListUserAgentMappings.vbs
To list the User-Agent mappings defined for the local array
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object, an FPCUserAgentMappings collection, an FPCUserAgentMapping object, and four strings.
Get references to the FPCArray object and FPCUserAgentMappings collection.
If the collection contains at least one FPCUserAgentMapping object that defines a User-Agent mapping, iterate through the collection and display the User-Agent header retrieved from the UserAgent property, the type of authentication that corresponds to the value of the FBAFormsType property, and an indication of whether the mapping is enabled based on the value of the Enabled property for each User-Agent mapping in the collection.
Script listing: ListUserAgentMappings.vbs
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script retrieves the collection of User-Agent mappings defined
' in an ISA Server array and displays the User-Agent header, the type
' of authentication specified, and an indication of whether the mapping
' is enabled for each User-Agent mapping in the collection.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
Const fpcFbaHTML4 = 0
Const fpcFbaCHTML = 1
Const fpcFbaXHTML_MP = 2
Const fpcFbaHTTPBASIC = 3
Sub ListUserAgentMappings()
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
' Declare the other objects needed.
Dim isaArray ' An FPCArray object
Dim mappings ' An FPCUserAgentMappings collection
Dim mapping ' An FPCUserAgentMapping object
Dim authType ' A String
Dim colSpace1 ' A String
Dim colSpace2 ' A String
Dim isEnabled ' A String
' Get references to the array object and
' the User-Agent mappings collection.
Set isaArray = root.GetContainingArray()
Set mappings = isaArray.RuleElements.UserAgentMappings
' Display the User-Agent mappings defined in the array.
If mappings.Count > 0 Then
WScript.Echo "No." & vbTab & "User-Agent headers" _
& vbTab & "Authentication type" _
& vbTab & "Enabled/disabled" & vbCrLf
For Each mapping In mappings
Select Case mapping.FBAFormsType
Case fpcFbaHTML4
authType = "HTML 4.01 forms"
Case fpcFbaCHTML
authType = "cHTML forms"
Case fpcFbaXHTML_MP
authType = "XHTML-MP forms"
Case fpcFbaHTTPBASIC
authType = "Basic authentication"
End Select
If Len(mapping.UserAgent) < 8 Then
colSpace1 = vbTab & VbTab & vbTab
Else
colSpace1 = vbTab & vbTab
End If
If authType = "Basic authentication" Then
colSpace2 = vbTab
Else
colSpace2 = vbTab & vbTab
End If
If mapping.Enabled = True Then
isEnabled = "Enabled"
Else
isEnabled = "Disabled"
End If
WScript.Echo mapping.order & vbTab & mapping.UserAgent _
& colSpace1 & authType & colSpace2 & isEnabled
Next
Else
WScript.Echo "No User-Agent mappings are defined."
End If
End Sub
ListUserAgentMappings
Creating a new User-Agent mapping
The Microsoft Visual Basic Scripting Edition (VBScript) code in AddUserAgentMapping.vbs (listed later in this document) creates a new User-Agent mapping, which maps the User-Agent headers specified by the user to the type of authentication specified by the user, in the list of User-Agent mappings for the local array. The User-Agent headers to which the new mapping is to apply are indicated in the first parameter by a string that may contain wildcard characters (*), and one of the following types of authentication is indicated in the second parameter:
- Forms-based authentication using HTML 4.01 forms
- Forms-based authentication using cHTML forms
- Forms-based authentication using XHTML-MP forms
- Basic authentication
This script, as presented, must be run on an ISA Server 2006 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
To use this script, paste the code in the script listing into a text editor, save it in a file named AddUserAgentMapping.vbs, and run it from a command prompt.
Usage:
CScript AddUserAgentMapping.vbs UAHeaders AuthType
UAHeaders specifies the User-Agent headers to which the new mapping is to apply.
AuthType specifies the type of authentication to be used for the User-Agent headers specified in UAHeaders. This parameter may be set to one of the following values:
- HTML4
- CHTML
- XHTML
- Basic
To create a new User-Agent mapping for the local array
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object, an FPCUserAgentMappings collection, and an FPCUserAgentMapping object.
Get references to the FPCArray object and FPCUserAgentMappings collection.
Call the Add method on the collection with the parameters supplied by the user to create the new User-Agent mapping.
Call Save on the collection of User-Agent mappings to write the changes to persistent storage.
Script listing: AddUserAgentMapping.vbs
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script creates a new User-Agent mapping that maps User-Agent
' headers to a type of authentication, which can be forms-based
' authentication (FBA) using forms written in a specific format or
' Basic authentication.
' This script can be run from a command prompt by entering the
' following command:
' CScript AddUserAgentMapping.vbs UAHeaders AuthType
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
' Define the constants needed.
Const Error_AlreadyExists = &H800700B7
Const fpcFbaHTML4 = 0
Const fpcFbaCHTML = 1
Const fpcFbaXHTML_MP = 2
Const fpcFbaHTTPBASIC = 3
Main(WScript.Arguments)
Sub Main(args)
If(args.Count <> 2) Then
Usage()
Else
Select Case UCase(args(1))
Case "HTML4"
AddUAMapping args(0), fpcFbaHTML4
Case "CHTML"
AddUAMapping args(0), fpcFbaCHTML
Case "XHTML"
AddUAMapping args(0), fpcFbaXHTML_MP
Case "BASIC"
AddUAMapping args(0), fpcFbaHTTPBASIC
Case Else
WScript.Echo "The AuthType parameter is not valid."
Usage()
End Select
End If
End Sub
Sub AddUAMapping(uaHeaders, authType)
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
' Declare the other objects needed.
Dim isaArray ' An FPCArray object
Dim mappings ' An FPCUserAgentMappings collection
Dim newMapping ' An FPCUserAgentMapping object
' Get references to the array object and
' the User-Agent mappings collection.
Set isaArray = root.GetContainingArray()
Set mappings = isaArray.RuleElements.UserAgentMappings
' Create a new User-Agent mapping.
On Error Resume Next
Set newMapping = mappings.Add(uaHeaders, authType)
If Err.Number = Error_AlreadyExists Then
WScript.Echo "A mapping for the User-Agent headers specified " _
& "already exists."
WScript.Quit
End If
On Error GoTo 0
' Save the changes to the collection of User-Agent mappings.
mappings.Save
WScript.Echo "Done!"
End Sub
Sub Usage()
WScript.Echo "Usage:" & VbCrLf _
& " " & WScript.ScriptName & " UAHeaders AuthType" & VbCrLf _
& "" & VbCrLf _
& " UAHeaders String that specifies User-Agent headers." _
& VbCrLf _
& " AuthType HTML4 FBA with HTML 4.01 forms" & VbCrLf _
& " CHTML FBA with cHTML forms" & VbCrLf _
& " XHTML FBA with XHTML-MP forms" & VbCrLf _
& " Basic Basic authentication"
WScript.Quit
End Sub
Editing or deleting a User-Agent mapping
The Microsoft Visual Basic Scripting Edition (VBScript) code in EditUserAgentMapping.vbs (listed later in this document) performs the action specified by the user on the User-Agent mapping specified by the user. The script can perform the following actions:
- Enable a User-Agent mapping.
- Disable a User-Agent mapping.
- Move a User-Agent mapping up one position in the list of mappings.
- Move a User-Agent mapping down one position in the list of mappings.
- Delete a User-Agent mapping.
For enabling, disabling, or deleting a User-Agent mapping, the User-Agent mapping on which the action is to be performed is indicated by specifying the number of the mapping or the string that specifies the User-Agent headers to which the mapping applies. For moving a User-Agent mapping up or down in the list of User-Agent mappings, the User-Agent mapping on which the action is to be performed is indicated by specifying its current number.
This script, as presented, must be run on an ISA Server 2006 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
To use this script, paste the code in the script listing into a text editor, save it in a file named EditUserAgentMapping.vbs, and run it from a command prompt.
Usage:
CScript EditUserAgentMapping.vbs Action Mapping
Action specifies the action that is to be performed on the User-Agent mapping specified in Mapping. This parameter may be set to one of the following values:
- ENABLE
- DISABLE
- UP
- DOWN
- DEL
Mapping specifies the User-Agent mapping on which the action is to be performed. For ENABLE, DISABLE, and DEL, this parameter may specify the number of the mapping or the string that specifies the User-Agent headers to which the mapping applies. For UP and DOWN, this parameter must specify the number of the mapping.
To edit or delete a User-Agent mapping defined for the local array
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object, an FPCUserAgentMappings collection, and an FPCUserAgentMapping object.
Get references to the FPCArray object and FPCUserAgentMappings collection.
Do one of the following:
- To enable the User-Agent mapping, call the Item method on the collection with the user-supplied mapping number or string that specifies the User-Agent headers to which the mapping applies to get a reference to the FPCUserAgentMapping object that represents the mapping and then set the Enabled property of this object to True.
- To disable the User-Agent mapping, call the Item method on the collection with the user-supplied mapping number or string that specifies the User-Agent headers to which the mapping applies to get a reference to the FPCUserAgentMapping object that represents the mapping and then set the Enabled property of this object to False.
- To move the User-Agent mapping up one position in the list of mappings, call the MoveUp method on the collection with the mapping number supplied by the user.
- To move the User-Agent mapping down one position in the list of mappings, call the MoveDown method on the collection with the mapping number supplied by the user.
- To delete the User-Agent mapping, call the Remove method on the collection with the user-supplied mapping number or string that specifies the User-Agent headers to which the mapping applies.
Call Save on the collection of User-Agent mappings to write the changes to persistent storage.
Script listing: EditUserAgentMapping.vbs
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script enables, disables, moves, or deletes the specified
' User-Agent mapping.
' This script can be run from a command prompt by entering the
' following command:
' CScript EditUserAgentMapping.vbs Action Mapping
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
' Define the constants needed.
Const Error_TypeMismatch = &HD
const Error_FileNotFound = &H80070002
const Error_InvalidParameter = &H80070057
Main(WScript.Arguments)
Sub Main(args)
If(args.Count <> 2) Then
Usage()
Else
EditMapping UCase(args(0)), args(1)
End If
End Sub
Sub EditMapping(action, mappingId)
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
' Declare the other objects needed.
Dim isaArray ' An FPCArray object
Dim mappings ' An FPCUserAgentMappings collection
Dim mapping ' An FPCUserAgentMapping object
' Get references to the array object and
' the User-Agent mappings collection.
Set isaArray = root.GetContainingArray()
Set mappings = isaArray.RuleElements.UserAgentMappings
' Perform the specified action on the specified User-Agent mapping.
On Error Resume Next
If action = "DEL" Or action = "ENABLE" Or action = "DISABLE" Then
If IsNumeric(mappingId) Then
mappingId = CInt(mappingId)
End If
End If
If action = "DEL" Then
mappings.Remove(mappingId)
If Err.Number = Error_FileNotFound Then
WScript.Echo _
"The User-Agent mapping specified could not be found."
WScript.Quit
Else
WScript.Echo "Removing the User-Agent mapping specified..."
End If
ElseIf action = "UP" Then
mappings.MoveUp(CInt(mappingId))
If Err.Number = Error_TypeMismatch Then
WScript.Echo _
"The Mapping parameter specified is not a number."
WScript.Quit
ElseIf Err.Number = Error_InvalidParameter Then
WScript.Echo "The mapping specified cannot be moved " _
& "or does not exist."
WScript.Quit
Else
WScript.Echo _
"Moving the User-Agent mapping specified up..."
End If
ElseIf action = "DOWN" Then
mappings.MoveDown(CInt(mappingId))
If Err.Number = Error_TypeMismatch Then
WScript.Echo _
"The Mapping parameter specified is not a number."
WScript.Quit
ElseIf Err.Number = Error_InvalidParameter Then
WScript.Echo "The mapping specified cannot be moved " _
& "or does not exist."
WScript.Quit
Else
WScript.Echo _
"Moving the User-Agent mapping specified down..."
End If
ElseIf action = "ENABLE" Then
Set mapping = mappings.Item(mappingId)
If Err.Number = Error_FileNotFound Then
WScript.Echo _
"The User-Agent mapping specified could not be found."
WScript.Quit
Else
If mapping.Enabled = False Then
WScript.Echo _
"Enabling the User-Agent mapping specified..."
mapping.Enabled = True
Else
WScript.Echo "The User-Agent mapping specified " _
& "is already enabled."
End If
End If
ElseIf action = "DISABLE" Then
Set mapping = mappings.Item(mappingId)
If Err.Number = Error_FileNotFound Then
WScript.Echo _
"The User-Agent mapping specified could not be found."
WScript.Quit
Else
If mapping.Enabled = True Then
WScript.Echo _
"Disabling the User-Agent mapping specified..."
mapping.Enabled = False
Else
WScript.Echo "The User-Agent mapping specified " _
& "is already disabled."
End If
End If
Else
WScript.Echo "The Action parameter specified is not valid."
Usage()
End If
On Error GoTo 0
' Save the changes to the collection of User-Agent mappings.
mappings.Save
WScript.Echo "Done!"
End Sub
Sub Usage()
WScript.Echo "Usage:" & VbCrLf _
& " " & WScript.ScriptName & " Action Mapping" & VbCrLf _
& "" & VbCrLf _
& " Action ENABLE Enable the mapping." & VbCrLf _
& " DISABLE Disable the mapping." & VbCrLf _
& " UP Move the mapping up one position." _
& VbCrLf _
& " DOWN Move the mapping down one position." _
& VbCrLf _
& " DEL Delete the mapping." & VbCrLf _
& " Mapping For ENABLE, DISABLE, and DEL, number of the" _
& VbCrLf _
& " mapping or string that specifies the User-Agent " _
& VbCrLf _
& " headers. For UP and DOWN, number of the mapping."
WScript.Quit
End Sub