|
|
Managing Active Directory Queries
Note: For General information about Hyena's Object Manager, click here.
Hyena's Active Directory integration is built around a very flexible and powerful query engine that is used to retrieve and display all Active Directory (AD) information. This query capability is used to retrieve information from any AD container or organizational unit (OU), and is also used when using the All Users, All Groups, etc. objects. While Hyena includes a number of pre-defined queries, the default queries can be completely modified, and entirely new queries with custom filters can also be created.
To create new AD queries or modify the existing queries that Hyena relies upon, use one of the following options:
Use the 
Object Manager (File->Manage Object View). The AD queries are managed on the AD Queries dialog.
Right click on any column heading in the right window when viewing the results of an AD Query and select Select / Customize Query... from the menu.
Right click on any AD object in the right window and select Select / Customize Query... from the menu.
Queries are divided into categories, referred to as a "Query Type" on the AD Queries dialog. These query types are actually pre-defined filters. For example, the All Users query type is designed to only show users. Except for the 'Container/OU Contents' query type, all of the pre-defined queries will show objects across the entire domain being managed. The All Users query type, for example, will display user objects from any container or OU regardless of where it is located in the AD structure.
To create or modify an AD query, first select the type of object from the Query Type list. Any existing queries defined for the selected query type will be listed in the Existing Queries list.
To create a new query, first click the New Query. button after selecting the Query Type. To modify an existing query's settings, click the Query Settings button. To add or modify a queries attributes (fields), see the Changing Query Attributes section below.
Changing Query Settings
Various settings control the name assigned to the query, and whether the query is used as default output in either of Hyena's windows, and in some instances, a custom filter. A query's settings consist of the following:
Query Name / Description - The query name is used for the display name on the Query Active Directory menu, as well as the identification name for the Existing Queries listing.
Default Window Assignment - Queries can optionally be assigned to be the default display for a given object category, such as All Users. Many Active Directory (AD) objects in Hyena's left (tree) window can be either expanded directly in the tree window by clicking on the 'plus' icon next to the object, or the contents can be displayed in the right (results) window by double-clicking on the object. These default actions are assigned to queries, which will automatically display the appropriate directory attributes. There are four (4) options for setting the default query window:
None - The 'none' option does not assign the query as a default. The query can be executed by selection from the Query Active Directory menu.
Tree - Use the output of this query when the plus ('+') icon is used to expand an object in the Tree (left) window.
Report - Use the output of this query by default when an object is double-clicked on to display the information in the Report (right) window.
Both - Use the results of this query by default in both the Tree (left) and Report (right) windows.
Notes:
Hyena will only display the first two (2) directory fields in the tree window. The second directory field will always be enclosed in parentheses ().
Hyena will not run a query when a single object, such as a user or group is double-clicked on. This action will always result in the display of the object Properties dialog.
LDAP Filters - A custom LDAP filter can be specified for any 'Container/OU Contents' query. See the next section for more information.
Using Custom LDAP Filters
Active Directory includes a powerful mechanism for filtering information at the directory level. The advantages of filtering data in this manner is that the filtering is performed at the server (domain controller), and only the matching information is returned to the application. This saves time and reduces network traffic, plus only returns to the application the information that is needed.
Hyena allows custom filters to be assigned to Container/OU query types. To specify or modify a custom filter, click the Query Settings button for any query, then either manually enter the filter criteria or use the Define... button to help create the filter. As an example, Hyena automatically includes two (2) queries that use custom filters, the All Disabled Users and All Contracts queries.
Custom filters can also be processed either for any selected Container/OU level, or for the entire subtree under a selected Container/OU. To have a filter process sub-containers, enable the "Include subcontainers and sub-OUs in search" option. If the main "Containers/OUs" object is selected for a domain when a filter is executed with this option enabled, the entire directory will be searched.
This filtering mechanism is entirely implemented by Microsoft's Active Directory, and Hyena has no direct control over many aspects of it. In particular, there isn't a way for Active Directory to know that a particular filter string is invalid or might produce unexpected results. If a filter string contains an invalid condition or syntax, Active Directory will generally return an empty set of results and will not display an error.
For more information on the syntax used by Active Directory filters, go to:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/adsi/adsi/search_filter_syntax.asp
This filtering mechanism is extremely powerful and also complex. A number of examples on the Microsoft website will help develop an understanding of how to construct complex filters.
Using Parameters in Filters
Hyena extends the Active Directory filtering feature by allowing parameters to be placed into the filter string. For example: An organization uses the 'department' attribute to divide it's user accounts by company department. The organization has three (3) departments: Sales, Finance, and Manufacturing. To create a different query for each department, three (3) queries would be needed:
(department=sales)
(department=finance)
(department=manufacturing)
This is somewhat inconvenient. With Hyena's 'Flexible Parameters' feature, you can instead create one filter, as follows:
(department=%%)
When the query containing this filter is executed, Hyena will prompt for the value of the department attribute. If desired, a default can be entered as well, as follows:
(department=%sales%)
This will place the value 'sales' in as a default when the query is executed.
Another example would be a typical address filter. In this example, the filter is to request the City, State, and Zip, as follows:
(L=%New York%)(St=%NY%)(PostalCode=%%)
In the example above, the query would default the City to 'New York', the State to 'NY', and the zip code would be blank. However, to drop the zip code from the search entirely, simply leave the zip code field blank when prompted. Hyena will automatically drop any filter condition with a blank value, which adds a great deal of flexibility when creating filters with parameters.
Notes:
Unlike the usage in file and directory searches, the '*' character when used in an LDAP filter will require that some value exist for the attribute that it is operating on. Since Active Directory does not store blank (null) values, a portion of a query with a search filter of "(company=*)" will only return objects for which some value is found in the 'company' attribute; objects that do not have the company attribute set (ie it's null), will NOT be returned.
Active Directory attribute names are case-insensitive. Most values are also case-insensitive depending on how they are defined in the directory.
Changing Query Attributes
The primary purpose of an Active Directory query, of course, is to display directory attributes (fields), and Hyena provides full flexibility in the creation and modification of the individual directory attributes displayed.
To change or add directory attributes to a query, first select the query to modify in the Existing Queries list. Hyena will display the query's current attributes in the lower left window, and display the current 'schema' in the lower right window. The schema list is divided into several sub-categories for easier attribute selection. However, any attribute can be selected and added to a query for any type of object.
Query attributes can be removed, added, or moved within the query. The order of the attributes determines the order of the display in Hyena. To change the title that is used to display an attribute, click the Modify... button.
One attribute can also be designated as the initial sort order for the query results by clicking on the Sort button.
Changing Query Menu Ordering and Adding Menu Separators
Hyena will display the queries for any given object type in the order shown in the Existing Queries list. To change the sequence of the queries when displayed in a menu, use the Move Up and Move Down buttons.
To add a separator to visually separate groups of custom queries, click the Insert Separator button.
Adding Custom Query Attributes
To add attributes that are not shown in the attribute list, click the dropdown combo box labeled Attribute Category on the AD queries dialog (after selecting the query that you want to modify). Select the "Other (specify attribute)" category. The resulting dialog will prompt for the name(s) of the attributes to add. To add multiple attributes, separate each attribute with a comma ( , ), or a new line by pressing Control-Enter.
While Active Directory contains a great deal of information, at time the data is not formatted for ease of use. For example, the directory does not have an attribute to indicate the name of the container that an object resides in. While this information is part of the directory path of the object, its not easy parsed out or visually easy to see.
Hyena supports a number of special 'symbols' that can be added to AD queries which will be calculated or programatically determined when the query is executed. To add a symbol to a query, set the Attribute Category to 'Special AD Symbols'. Some of these can affect the performance of getting back the query results. The following special symbols can be added to a query; Before adding any of these symbols to an AD query, read the information below for specific performance impacts:
%SYM_AD_USER_NO_CHG_PWD%
When this symbol is added to a query, Hyena will call a Windows function to retrieve additional information to determine the status of the 'user cannot change password' setting. This function must be called on each user account, and can therefore increase the time required to process the AD query. Test using this function first on a small subset of users accounts. Its usage should only be needed if the user account flags (useraccountcontrol attribute) is not accurate with respect to this particular setting.
If this symbol is added to a query, and the user icon rule (Tools->Settings->Active Directory (User Icons...) for 'user cannot change password' is enabled, the user icon will reflect the same data retrieved for this symbol. See the using Customized User Images topic for more information.
Performance: Potentially a significant performance impact when added to a query. Best added to queries that are NOT run by default.
%SYM_AD_CONTAINER%
Calculates the AD container path, which is essentially the DN without the leading name (CN) of the object. For example, if the entire user DN is:
CN=JackieJohnson,OU=Sales,OU=Marketing,DC=mydomain,DC=com, then the AD container will be:
OU=Sales,OU=Marketing,DC=mydomain,DC=com
Performance: No performance impact when added to a query.
%SYM_AD_CONTAINER_NODOMAIN%
Using the above example, this symbol value would be:
OU=Sales,OU=Marketing
Performance: No performance impact when added to a query.
%SYM_AD_TOP_CONTAINER%
Using the previous example, this symbol value would be:
Sales
Performance: No performance impact when added to a query.
%SYM_DAYS_UNTIL_EXPIRE%
Displays the number of days left until the account expires, based on the account expiration date.
Performance: Small performance impact, as the account expiration date must be retrieved/computed.
%SYM_PWD_AGE%
Displays the number of days since the password was changed.
Performance: Small performance impact, as the 'pwdlastset' attribute must be retrieved/computed.
Executing Active Directory Queries
See the Using Active Directory Queries and Views section for more information on how to execute queries.
Customizing the Group Member Display
To modify the query that executes when members are displayed for a group, use one of the following options:
• Select the "Select / Customize Member Query..." option from the "View Group Members" menu.
• Select File > Manage Object View, select the 'AD Queries' tab, then change the Query Type to "Group Members". Modify the default query named "Group Members", or create a new query if desired.
Modification of the query attributes for group members is the same as other directory queries: Select the desired fields from the Schema Attribute list; change the Attribute Category as needed to display the appropriate attributes.
Since the directory query for group members will be specific to the group member, special symbols are used to represent attributes for the parent group. To select one or more of these special symbols, change the 'Attribute Category' list to 'Special AD Symbols', and add one or more of these symbols to your query:
%SYM_AD_GROUP_SAM% - Use this symbol to include the 'samaccountname' attribute of the parent group to the query.
%SYM_AD_GROUP_TYPE% - Use this symbol to include the 'grouptype' attribute of the parent group to the query. The group type will be converted into a readable representation of the group type and security setting, ie "Local (Security)".
%SYM_AD_GROUP_EMAIL% - Use this symbol to include the 'mail' attribute (email address) of the parent group to the query.
%SYM_AD_GROUP_MANAGEDBY% - Use this symbol to include the 'managedby' attribute of the parent group to the query.
%SYM_AD_GROUP_SID% - This symbol will include a human-readable SID of the parent group to the query.
%SYM_AD_GROUP_DESC% - Use this symbol to include the 'description' attribute of the parent group to the query.
%SYM_AD_GROUP_MEMBERSHIP% - This symbol will be replaced with the type of membership the group member is derived from:
DIRECT - Represents a direct member in the group
INDIRECT - Represents an indirect member, ie the user/group is a member from another nested group member. This type of membership will only be visible if the group member query was for direct and indirect members.
PRIMARY - Group member (must be a user) is a member through the user's primary group setting.
DYNAMIC - Group member is dynamic, which only applies if the group is a dynamic group.
%SYM_AD_GROUP_NAME% - Use this symbol to include the directory name of the parent group to the query.
%SYM_AD_GROUP_PATH% - Use this symbol to include the directory path of the parent group to the query.
The group membership display can be modified for direct group member listings, indirect group member listings, as well as listing the current members of dynamic groups.
To get a group membership query to display direct and indirect members, enable the option to "View Direct and Indirect Member" on the bottom of the Query Properties. This is the same dialog used to specify the query name.