FPCUserAgentMapping Object
The FPCUserAgentMapping object represents a mapping of User-Agent headers to a type of authentication.
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. When a Web listener is configured to use forms-based authentication, Forefront TMG uses the User-Agent header in Web requests and the User-Agent mappings configured in the array to ascertain whether forms-based authentication can be performed and to determine the specific form that should be provided for forms-based authentication.
The User-Agent headers to which a User-Agent mapping applies are specified by the UserAgent property, which holds a string that may contain wildcard characters (*). A User-Agent mapping whose UserAgent property is set to a wildcard character (*) applies to all User-Agent headers. A User-Agent mapping whose UserAgent property is set to a string that begins and ends with a wildcard character 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 a specific format and Basic authentication. Forefront TMG supports forms for forms-based authentication that are written in the following formats:
- HTML 4.01.
- cHTML.
- XHTML-MP.
The following User-Agent mappings are supplied with Forefront TMG:
| 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 Forefront TMG needs to authenticate a Web proxy 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, Forefront TMG reads the User-Agent header in the Hypertext Transfer Protocol (HTTP) GET request and uses it to find the applicable User-Agent mapping. Note that the last User-Agent mapping is a default mapping that specifies Basic authentication as a fallback authentication method.
Forefront TMG 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, Forefront TMG sends back a 302 response that redirects the client to the XHTML-MP form. When a GET request is sent from Internet Explorer, Forefront TMG 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.
Note The properties of the FPCUserAgentMapping object cannot be accessed through Forefront TMG Management.
The FPCUserAgentMapping object is an element of an FPCUserAgentMappings collection, and a new object representing a User-Agent mapping can be created by calling the Add method of this collection.
.png "Dd421394.bkbutton(en-us,MSDN.10).png")
Click here to see the Forefront TMG object hierarchy.
Inheritance
This object inherits from the FPCPersist object, which contains methods and properties related to the persistent storage of an object's data. They include methods for exporting an object's data to and importing it from XML documents.
Methods
The FPCUserAgentMapping object does not define any methods.
Properties
The FPCUserAgentMapping object defines the following properties.
| Property | Description |
|---|---|
Gets or sets the description of the User-Agent mapping. |
|
Gets or sets a Boolean value that indicates whether the User-Agent mapping is enabled. |
|
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. |
|
Gets the ordinal 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. |
|
Gets or sets a string that specifies the User-Agent headers. |
Methods Inherited from FPCPersist
| Name | Description |
|---|---|
| CancelWaitForChanges | Cancels the registration established by the WaitForChanges method (for use in C and C++ programming only). |
| CanImport | Returns a Boolean value that indicates whether the object's properties can be imported from the specified XML document. |
| Export | Writes the stored values of all of the object's properties to the specified XML document. |
| ExportToFile | Writes the stored values of all of the object's properties to the specified XML file. |
| GetServiceRestartMask | Retrieves a 32-bit bitmask of the FpcServices enumerated type that specifies which services need to be restarted for currently unsaved changes to take effect. |
| Import | Copies the values of all of the object's properties from the specified XML document to persistent storage. |
| ImportFromFile | Copies the values of all of the object's properties from the specified XML file to persistent storage. |
| LoadDocProperties | Provides the XML document's properties so that you can know what information can be imported from the document. |
| Refresh | Reads the values of all of the object's properties from persistent storage, overwriting any changes that have not been saved. |
| Save | Writes the current values of all of the object's properties to persistent storage. |
| WaitForChanges | Registers to wait for an event indicating that the contents of the object have changed (for use in C and C++ programming only). |
Properties Inherited from FPCPersist
| Name | Description |
|---|---|
| PersistentName | Gets the persistent name of the object. The persistent name of an object is a name that is unique for the object at the respective level of the COM object hierarchy. |
| VendorParameterSets | Gets an FPCVendorParametersSets object that can hold sets of custom data for extending the object. |
Interfaces for C++ Programming
This object implements the IFPCUserAgentMapping interface.
Requirements
| Client | Requires Windows 7 or Windows Vista. |
| Server | Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2. |
| Version | Requires Forefront Threat Management Gateway (TMG) 2010. |
| IDL | Declared in Msfpccom.idl. |
See Also
Send comments about this topic to Microsoft
Build date: 6/30/2010