Managing User-Agent Mappings

Article
12/12/2007

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.

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

Managing User-Agent Mappings

On this page

Listing User-Agent mappings

Script listing: ListUserAgentMappings.vbs

Creating a new User-Agent mapping

Script listing: AddUserAgentMapping.vbs

Editing or deleting a User-Agent mapping

Script listing: EditUserAgentMapping.vbs

Additional resources