Share via

Registering Web Filters in Enterprise Edition

  • Article

In Forefront TMG Enterprise Edition, multiple Forefront TMG servers can be joined to the same array. In the case of a standalone array, one of the servers is designated as the array manager, from which the array-level configuration settings of the other array members are updated. When an Enterprise Management Server (EMS) is deployed, multiple enterprise arrays can be created within a single enterprise. The EMS stores both enterprise-level and array-level configuration settings and centrally manages all the arrays in the enterprise. In this case, each array member obtains the enterprise configuration settings and the array configuration settings for its array from the central EMS and maintains a locally stored effective configuration that is derived from the enterprise and array configurations. Web filters can be registered in the Web filters collections in the enterprise configuration and in array configurations. The Web filters collection in the enterprise configuration is not ordered, while the Web filters collection in an array configuration is ordered and provides methods for changing the ordinal position of each Web filter in the collection.

In addition, Forefront TMG Management can be extended for a Web filter by adding property pages for configuring the Web filter on the enterprise and array levels.

A Web filter can work on a Forefront TMG server only if all of the following conditions are met:

  • Its dynamic-link library (DLL) is copied to the computer.
  • The Web filter is registered as an object in the configuration of the computer's array.
  • The Web filter is registered as being installed on the computer.

Registering the Web filter in the array configuration is required for enforcing its policy in the array. Registering a Web filter in the enterprise configuration is optional, but provides several benefits. When you register a Web filter in the enterprise configuration, you can do the following:

  • Introduce an enterprise-wide configuration by attaching vendor parameters sets to the Web filter object and enterprise nodes that will be available to all Forefront TMG servers in all arrays in the enterprise.

    The configuration settings in a vendor parameters set created on an enterprise-level object are combined into the effective configuration stored locally on each Forefront TMG server and can be retrieved by a Web filter by accessing the vendor parameters sets attached to the corresponding array-level object. In particular, the vendor parameters sets attached to an enterprise-level Web filter object can be retrieved by the Web filter through the FPC.GetContainingArray.Extensions.WebFilters(Filter_GUID).VendorParametersSets property. If two vendor parameters sets with different globally unique identifiers (GUIDs) are defined for a Web filter, one in the enterprise configuration and one in the array configuration, the Web filter can access both of them through this property.

  • Enable or disable the Web filter in the enterprise configuration. If a Web filter is enabled in the enterprise configuration, the enterprise setting is applied to each array, and the filter cannot be disabled in an array configuration. If a Web filter is disabled in the enterprise configuration, it can be enabled or disabled in an array configuration.

  • Extend Forefront TMG Management by adding property pages for setting enterprise configuration settings for the Web filter.

The Setup code for a Web filter may offer the following registration options:

  • Registering the Web filter as an object in the enterprise configuration. This option is needed only if the Web filter is enterprise-aware.
  • Registering the Web filter as an object in an array.
  • Installing and registering the Web filter on an array member.
  • Registering the Forefront TMG Management extension for the Web filter. This option is needed only if configuration settings are defined for the Web filter in one or more vendor parameters sets.

Registering and Unregistering the Web Filter in the Enterprise Configuration

The process of registering and unregistering a Web filter as an object in the enterprise configuration stored on the EMS includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified EMS with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator.
  3. Using the FPC.Enterprise property to get a reference to the FPCEnterprise object.
  4. Using the FPCEnterprise.Extensions property to get a reference to the FPCExtensions object for the enterprise configuration.
  5. Using the FPCExtensions.WebFilters property to get a reference to the FPCWebFilters collection.
  6. Calling the FPCWebFilters.Add method with the Web filter's GUID, the filter's name, the path for storing the filter's DLL, including the file name of the DLL, relative to the Forefront TMG installation folder, the filter's priority, and the filter's direction, or calling FPCWebFilters.Remove to unregister the Web filter in the enterprise configuration and skipping the next step. Note that the path and priority supplied in the call to the Add method are ignored in the enterprise configuration.
  7. Setting the vendor parameters sets and additional properties of the Web filter.
  8. Calling the Save method on the FPCWebFilters collection to write the changes in the stored enterprise configuration.
  9. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the EMS.

If an enterprise administrator wants to register a Web filter in the enterprise configuration from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the EMS before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Registering and Unregistering the Web Filter in an Array

In Forefront TMG Enterprise Edition, an enterprise administrator can create an empty array and add a Web filter to the array configuration before joining any Forefront TMG servers to the array. This code is applicable to registering and unregistering the Web filter in an empty array or in an array that has array members.

Administrators should run this code only once to register the Web filter in an array. It can be run on a remote management computer, an array manager, an EMS, or an array member. If this code is run on an array member, it also registers or unregisters the Web filter as an installed Web filter on the array member.

The process of registering and unregistering a Web filter in an array includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified array manager or EMS with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator. This step can be skipped when Setup is run on the array manager or EMS.
  3. Using the FPC.Arrays property to get a reference to the FPCArrays collection of the arrays collection.
  4. Calling the FPCArrays.Item method to get a reference to the FPCArray object representing the array.
  5. Using the FPCArray.Extensions property to get a reference to the FPCExtensions object for the array.
  6. Using the FPCExtensions.WebFilters property to get a reference to the FPCWebFilters collection for the array.
  7. Calling the FPCWebFilters.Add method with the Web filter's GUID, the filter's name, the path for storing the filter's DLL, including the file name of the DLL, relative to the Forefront TMG installation folder, the filter's priority, and the filter's direction, or calling FPCWebFilters.Remove to unregister the Web filter in the array and skipping the next step. Note that a Web filter can be removed from an array configuration only after all the references to it in the FPCRefs collection stored in the InstalledWebFilters property of every member of the array have been removed.
  8. Setting the vendor parameters sets and additional properties of the Web filter, particularly its description, the name of the vendor who supplied it, and the version number.
  9. Registering events and alerts in the array configuration (optional). For more information about creating an event and alert in an array, see Signaling Events and Alerts.
  10. Calling the Save method on the FPCWebFilters collection to write the changes in the stored enterprise configuration.
  11. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the array manager or EMS. This step can be skipped when Setup is run on the array manager or EMS.

Steps for changing the order of the filters in the collection using the FPCWebFilters.MoveDown and FPCWebFilters.MoveUp methods may be added.

After these steps are performed, the Web filter can be installed and registered on the array members.

If this code is run on an array member to register the Web filter in its array, the DLL should be copied to the computer and stored in the location that will be passed in the RelativePath parameter of the FPCWebFilters.Add method sometime before this method is called. When the FPCWebFilters.Add method is called to register the Web filter in the array, this method also registers the Web filter as being installed on the array member by creating a reference to the new FPCWebFilter object in the FPCRefs collection stored in the InstalledWebFilters property of the local Forefront TMG server.

After a Web filter is registered in an array, a Web filter not registered alert may be issued on array members that have the filter in their array configuration, but do not have a reference to it in their InstalledWebFilters property. This alert indicates that the steps required to install and register the Web filter on those array members must still be performed. We recommend resetting this alert after the filter is registered on all the array members.

If an enterprise administrator wants to register a Web filter in an array from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the array manager or EMS before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Installing and Registering the Web Filter on an Array Member

The process of installing and uninstalling a Web filter on an array member after the Web filter has been registered in the array includes the following steps:

  1. Copying the Web filter's DLL to the array member and storing it in the location that was specified in the RelativePath parameter of the FPCWebFilters.Add method when the Web filter was registered in the array.
  2. Creating an instance of the FPC root object and obtaining a reference to it.
  3. Calling the FPC.GetContainingServer method to get a reference to the FPCServer object representing the Forefront TMG server.
  4. Using the FPCServer.InstalledWebFilters property to get a reference to the FPCRefs collection of references to the Web filters installed on the server.
  5. Calling the FPCRefs.Add method and specifying the Web filter's GUID in the Name parameter to create a reference to the FPCWebFilter object in the FPCRefs collection stored in the InstalledWebFilters property of the local Forefront TMG server, or calling FPCRefs.RemoveSpecified and specifying the Web filter's GUID in the Name parameter to unregister the Web filter as being installed on the array member. Note that the FPCRefs.Add method will fail with HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) if the Web filter was installed by running the option to register the Web filter in the array on the array member. This error should be ignored.
  6. Calling the Save method on the FPCServer object to write the changes in the stored array configuration.

Registering the Forefront TMG Management Extension for the Web Filter

For information about creating an extension to Forefront TMG Management for a Web filter and registering the extension, see Extending Forefront TMG Management.

Send comments about this topic to Microsoft

Build date: 6/30/2010