Posted: 5/25/2010, Updated: 11/6/2013
Identity Finder has a multitude of settings to customize searches, the user experience, and communication with the Enterprise Console. These settings are defined in an xml file used by the Enterprise Console to define the settings available within policies. The policy definitions can also be used as a reference guide to help with the customized configuration of a policy, configuration file, or to add to a customized installation package.
This article contains the following sections:
- Policy Definitions Explanation and Download Link
- Settings Viewer Description and Usage
- Settings Locations and Priorities
- User Default Policies, FirstRun Container, FirstRun and AlwaysUseFirstRun Settings
- Settings Notes
Policy definitions are updated whenever a new setting is added to an Identity Finder client or a change is made to an existing setting. Policy definitions can be downloaded and applied from within the console itself. When using the Settings Viewer (described below), it is necessary to manually download the latest policy definitions and place the policydefinitions.xml file in the same folder as the application executable .
The Identity Finder Settings Viewer is a stand-alone reference tool that describes all of the settings available for the client applications. This tool provides the ability to view and search for any available setting but does not display the current state of any setting, cannot be used to configure settings, and does not provide the ability to create or export policies. All settings can be viewed and configured via the policy editor within the enterprise console, but when the console is not available or an offline reference is desired, the viewer can be utilized.
This application is Windows only and requires the .NET Framework v4.0. The settings viewer is attached to this article.
To open the settings viewer, follow these steps:
- Ensure that .NET Framework v4.0 or later is installed on the computer that will run the settings viewer.
- Click on the link for IdentityFinderSettingsViewer.zip at the bottom of this article, save it on the local computer and unzip the contents into a new folder.
- Download the latest policy definitions and copy them to the same folder used in step 2.
- Navigate to the folder used in steps 2 & 3 and double click on IdentityFinderSettingsViewer.exe.
The settings viewer has 3 main components:
- Toolbar - allows the settings to be exported to a .docx file that can be opened in Microsoft Word 2007 or later, exported to an html file, exported in a format to be used with security templates (though this process is not recommended), and provides a search capability
- Settings Tree - provides a hierarchical list of all available settings for Windows and Mac
- Details Pane - provides all the information about a particular setting
- Setting Name: Name of the setting itself (Note: settings names are case sensitive)
- Setting Type: Bit (the only valid values are 0 and 1), Integer (any number greater than or equal to 0), String (a human readable string), or Binary (a non-human readable blob)
- Allow Multiple: For integers, this means that the options can be logically OR'd together. For strings, this means that in an xml configuration file there are multiple "option" elements, in the Windows registry the type is REG_MULTI_SZ and in a Mac XML, there is an array of string elements.
- Requires Restart: Notes if the client is required to restart before a change to that setting can be applied
- Platform: Win, Mac or All
- Description: Brief text that is displayed in the console in the description column
- Explanation: Detailed text that is displayed in the console after double-clicking on a setting (The Expand button opens the explanation in a new window to provide easier viewing for long explanations)
- Options: The valid values for the setting
- Value: The actual value used by the client
- Name: Description of the value displayed in console after double-clicking on a setting
- Default: True or False - the value used by the application if it is not set in any settings location
- Platform: Win, Mac, or All
- Explanation (reserved for future use): Detail text about an option (The Explanation button opens the explanation in a new window to provide easier viewing for long explanations)
- Default Value (not always displayed): The value used by the application if it is not set in any settings location
- Client UI: If available, information about the setting as it appears in the client user interface
- Platform: Win or Mac
- Location: The location of the setting in the client user interface
- Description: The exact text that appears in the client
Settings can be configured in a variety of ways, though most organizations will only need to configure a few settings via a customized installation package to establish communication between the clients and console and then will manage the rest of their settings via policy within the Enterprise Console. Settings may be specified via Policies (System, User, and Scheduled Task), Configuration files (XML and Property Lists), and/or Customized installation packages (MSI and PackageMaker)
When a specific setting is configured in multiple sources, it may be necessary to analyze the order in which the settings are applied to understand the effect on the client. At a high level, settings are applied in the following order:
- System policies (applied in the order of their priority as defined in the Enterprise Console)
- System settings locally defined on the client (e.g., in HKEY_LOCAL_MACHINE on Windows or in an XML file on Mac)
- Scheduled Task policies
- Configuration files supplied via a command line switch
- User Default policies
- User settings locally defined on the client (e.g., in HKEY_CURRENT_USER on Windows or in a user XML file on Mac)
- Internal application defaults
When settings are present in a system policy or locally defined in a system location, they are considered to be authoritative and the corresponding options in the client UI will be disabled and therefore users will be unable to change those settings. These setting persist across sessions, take precedence over all other settings, and will be in effect until the system setting is changed. (Cases 1 and 2 above)
When settings are present in a scheduled task policy, they are considered to be authoritative and the corresponding options in the client UI will be disabled and therefore users will be unable to change those settings. These settings are only in effect for the duration of the scheduled task and will not persist across sessions. Settings that are also specified in a system location will be ignored as the system settings have a higher priority. (Case 3 above)
When settings are present in a configuration file, they are considered to be authoritative and the corresponding options in the client UI will be disabled and therefore users will be unable to change those settings. These settings are only in effect for that session and will not persist across sessions. Settings that are also specified in a system location will be ignored as the system settings have a higher priority - though this behavior can be modified through the use of the setting Settings\Initialization\Configuration\AllowConfigurationFileToOverrideSystemSetting. (Case 4 above)
When settings are present in a user default policy, they will be read if no search has been completed on the client (e.g., it is the client's "FirstRun"). These settings are not authoritative and the user will be able to change the settings in the client UI. If no search is completed, the settings will be read again the next time the client is started - overwriting any changes that the user made, but if a search was completed, these settings will be ignored. Please see User Default, FirstRun and AlwaysUseFirstRun. Settings that are also specified in any location noted above will be ignored as the other settings have a higher priority. (Case 5 above)
When settings are locally defined in a user location on the client (e.g., in the user profile) or the application default is used, they are not authoritative and the user will be able to change those settings in the client UI. Settings that are also specified in any location noted above will be ignored as the other settings have a higher priority. (Cases 6 & 7 above)
If a setting is not specified in any source (see Settings Locations and Priorities), the first time the application is run, the value of the Settings\Initialization\Configuration\FirstRun is 1 (True) and application default values will be used. Once the first search is completed, the value of FirstRun is set to 0 (False).
If a user default policy is applied and FirstRun is True, those settings will be used rather than the application defaults. Similarly, if settings are specified in a system location but in a FirstRun container and FirstRun is true, those settings will be used rather than the application defaults. These settings are not authoritative and the user will be able to change their values in the client UI.
To use the user default policy settings or the FirstRun container settings every time the client is launched, the setting Settings\Initialization\Configuration\AlwaysUseFirstRun must be set to 1 (Always reset settings) and this setting must be specified in a separate, system policy. When set, this will allow the user to change the settings in the client UI, but those settings will be reset the next the client is executed.
When configuring settings, it is important to note the following:
- Settings names are case sensitive
- All settings that accept a full path support the use of Windows environment variables such as %systemroot% or Mac environment variables such as $HOME
- The default value for a setting may differ based on the Edition of the software (e.g., Home Edition vs. Enterprise Client) and the defaults listed in the policy definitions apply to the Enterprise Client
- The default value for a setting may differ if one or more command line switches are supplied