Chapter 10 Editing Configuration Objects

This chapter introduces an Identity Manager component called a configuration object. Configuration objects store persistent customizations to Identity Manager. They are cached object types, which means that all configuration objects are brought into memory, and the cache is subsequently flushed, whenever a configuration object is changed. Speaking broadly, with the large exception of User objects and TaskInstances, most objects in the Identity Manager repository are configuration objects.

Editing configuration object properties is one way of implementing persistent changes to Identity Manager behavior. This appendix describes how to view and edit configuration objects. The information is organized as follows:

• Data Storage

• Viewing and Editing Configuration Objects

• Refreshing User Objects

Data Storage

Sun Identity Manager repository stores configuration object data in the following tables:

This is not a comprehensive list of tables; only relevant tables are listed here.

• object. Stores most of the Identity Manager application’s configuration objects, which include:

  • SystemConfiguration objects

  • TaskDefinition objects

  • WorkItem objects

  • Form objects

  • Resource objects

• task. Stores TaskInstances and WorkItems (in other words, the nonstatic instances of Workflows).

• org. Stores all Identity Manager organizational information.

• userobj. Stores all the Identity Manager enterprise identities. These identities are simply containers for accounts on managed systems.

• account. Stores the accounts identified on a managed system.

  ---

  Note –

  This is the table being referenced when someone “builds the account index.” Each managed system has a set number of accounts in this table after reconciliation or account linking.

  ---

• log. Stores all audit events and log type information.

A key concept to understand in the Identity Manager repository is that all data is stored in two ways, where each table has indexed and keyed columns used to query objects and each table has an XML column used to store the entire ASCII representation of the object (depending on the database engine this is typically a BLOB or MEDIUM TEXT data type). Identity Manager stores data in this way because all Identity Manager objects are de-serialized from Java objects to ASCII XML for storage in the repository.

The application, at a high level, queries by the indexed columns, pulls back XML ASCII text and then serializes the XML into Java objects. These objects are usually made available through the use of views (such as User view and Password view).

Object Naming Conventions

Do not use the following characters in any Identity Manager object names:

Avoid using other special characters in object names, such as the following, to prevent potential errors:

Viewing and Editing Configuration Objects

Editing configuration object properties is one way of implementing persistent changes to Identity Manager behavior.

You can use the Sun Sun Identity Manager Integrated Development Environment (Identity Manager IDE) to view and edit Identity Manager objects for your deployment. Instructions for installing and configuring the Identity Manager IDEare now provided on https://identitymanageride.dev.java.net.

This section describes how to view and edit the following configuration objects:

• IDM Schema Configuration Object

• UserUIConfig Object

• RepositoryConfiguration Object

• WorkItemTypes Configuration Object

• SystemConfiguration Object

• Role Configuration Object

• End User Tasks Object

• An object’s authType determines who can view or edit the configuration object.

  To assign an authorization type to an object, you set a new field defined in the PersistentObject class. From the Java API, you can access the authorization type using these methods:

  public void setAuthType(String name);
  public String getAuthType();

  In the XML for an object, you can set the authType attribute in the root element. For example:

  <TaskDefinition name=’Request More Space’ authType=’EndUserTask’
      executor=’com.waveset.workflow.WorkflowExecutor’ ...>
      ...
  </TaskDefinition>

• If you change the inline or queryable attributes for Type.USER, you must refresh all User objects.

  For more information, see Refreshing User Objects.

IDM Schema Configuration Object

You configure User and Role extended, queryable, and summary attributes in the IDM Schema Configuration configuration object.

The schema customizations provided in the IDM ObjectClass Configuration object are loaded at server startup. Whenever you modify the schema, you must restart the server to load the changes.

Identity Manager records any problems loading the schema in the system log messages. Use one of the following methods to view these messages:

• Run the lh syslog command

• Run the ’Recent System Messages’ report from the IDM Administrator Interface (Reports tab)

A sample of the schema can be found in the schema.xml file in the sample directory.

Edit the IDM Schema Configuration configuration object to add extended attributes to multiple object types during deployment. Specifically, you can

• Configure extended, queryable and summary attributes for Users, Roles, Business Roles, IT Roles, Application Roles, Asset Roles, and any custom roles

• Mark extended and built-in attributes as queryable or summary

The IDM Schema Configuration object is protected with the IDMSchemaConfig authType.

Administrators needing to view or edit the Identity Manager schema for Users or Roles must have the IDMSchemaConfig AdminGroup (capability) assigned. The Configurator user has this AdminGroup assigned by default.

Adding an Extended Attribute to an Object

To add an extended attribute, you must define the attribute with an IDMAttributeConfiguration (unless the attribute is a built-in attribute).

IDMAttributeConfigurations require a name and syntax. The valid syntax options are BOOLEAN, DATE, INT, or STRING. Optionally, an IDMAttributeConfiguration can specify whether the attribute is multi-valued, and can provide a display name (currently not used), and a description.

To add an extended attribute, or mark an attribute (either extended or built-in) as queryable or summary, specify an IDMObjectClassAttributeConfiguration in the appropriate IDMObjectClassConfiguration, such as User. You must specify a name that matches an existing (built-in or configured in the same configuration object) IDMAttributeConfiguration. You can also mark the IDMObjectClassAttributeConfiguration as queryable or summary.

In the following example, firstname, lastname, and fullname are extended attributes. The firstname and lastname User attributes are queryable and summary, but fullname is not.

Example 10–1 Extended Attributes Example

<?xml version=’1.0’ encoding=’UTF-8’?> <!DOCTYPE Waveset PUBLIC ’waveset.dtd’ ’waveset.dtd’> 
<Waveset> 
<Configuration name="IDM Schema Configuration" id=’#ID#Configuration:IDM_Schema_Configuration’ 
authType=’IDMSchemaConfig’> 
<IDMSchemaConfiguration> 
<IDMAttributeConfigurations> 
... 
<IDMAttributeConfiguration name=’firstname’ description=’User’s first name’ syntax=’STRING’/> 
<IDMAttributeConfiguration name=’lastname’ description=’User’s last name’ syntax=’STRING’/> 
<IDMAttributeConfiguration name=’fullname’ description=’User’s full name’ syntax=’STRING’/> 
... 
</IDMAttributeConfigurations> 
<IDMObjectClassConfigurations> 
... 
<IDMObjectClassConfiguration name=’User’ extends=’Principal’> 
... 
<IDMObjectClassAttributeConfiguration name=’firstname’ queryable=’true’ summary=’true’/> 
<IDMObjectClassAttributeConfiguration name=’lastname’ queryable=’true’ summary=’true’/> 
<IDMObjectClassAttributeConfiguration name=’fullname’/> 
... 
</IDMObjectClassConfiguration> 
</IDMObjectClassConfigurations> 
</IDMSchemaConfiguration> 
</Configuration> 
</Waveset>

To prevent potential conflicts with new core attributes in future releases of Sun Identity Manager, prefix extended attributes with a deployment-specific prefix.

For example, to add an extended attribute to User to record the employeeNumber, prefer a prefix associated with the company, such as acme_employeeNumber. If a future release of Identity Manager incorporates a built-in user attribute named employeeNumber, the two attributes will remain distinct. Otherwise the built-in attribute takes precedence.

Extending the Role Object Class

You can extend Role using an IDMObjectClassConfiguration. The following built-in Role extensions all extend the Role object class:

• BusinessRole

• ITRole

• AssetRole

• ApplicationRole

To add an extended attribute to a particular role extension, such as AssetRole, add the IDMObjectClassAttributeConfiguration to the AssetRole IDMObjectClassConfiguration. To add an extended attribute to all kinds of roles, add the IDMObjectClassAttributeConfiguration to the Role IDMObjectClassConfiguration, and it will be inherited by all extensions of Role.

You can define custom extensions of Role or any extension of Role. For example, to add a custom extension of AssetRole, define a new IDMObjectClassConfiguration (in the IDM Schema Configuration) for the new role, and use the extends field to specify the parent role, as shown in the following example:

<IDMObjectClassConfiguration name=’MyAssetRole’
                             extends=’AssetRole’
                             description=’My Asset Role Description’/>

When you add a new Role objectclass, you must add a new Role type to the Role Configuration object. In addition, the new Role type’s name must match the name of the new Role objectclass. For more information, see Role Configuration Object.

UserUIConfig Object

You now configure extended, queryable, and summary attributes for Users (WSUser) in the schema configuration instead of in the UserUIConfig object. For more information, see IDM Schema Configuration Object

The SummaryAttrRoleCountLimit attribute controls the number of roles that appear in the summary attribute string for a user. To control this number, specify a value here. If you do not specify a value in this object, Identity Manager will list at most three roles.

RepositoryConfiguration Object

The RepositoryConfiguration object contains settings that control the behavior of the Identity Manager Repository. Each XML attribute of the top-level <RepositoryConfiguration> element configures some aspect of overall Repository behavior.

For example, the following line specifies that repository locks expire in five minutes by default.

<RepositoryConfiguration ... lockTimeoutMillis=’300000’ ... >

Do not modify any RepositoryConfiguration setting unless you understand its effects.

The RepositoryConfiguration object also contains some settings that are specific to User objects. For example, the TypeDataStore element for User objects specifies the inline attributes for User objects.

Inline attributes are single-valued attributes that the Repository stores directly in the main object table for each type, in this case, in columns attr1 through attr5 of the USEROBJ table. Most attribute values are stored in the USERATTR table (which requires a separate join for each attribute). Inlining an attribute improves the performance of queries that use the attribute.

The sample RepositoryConfiguration object specifies default inline attributes for User objects, as follows:

<TypeDataStore typeName=’User’ ... attr1=’MemberObjectGroups’ \
  attr2=’lastname’ attr3=’firstname’ attr4=’’ attr5=’’ />

Do not change the value of attr1, which is set to attr1=’MemberObjectGroups’. You can, however, specify the name of any attribute that is queryable and single-valued as the value of any of the remaining inline columns (attr2 through attr5).

• If you change the inline attributes for Type.USER, you must refresh all User objects.

  For more information, see Refreshing User Objects.

• Changes to the RepositoryConfiguration object do not take effect until you restart each Identity Manager server. Restarting an Identity Manager server restarts the Repository on that server, which causes the Repository to re-read the RepositoryConfiguration object.

To view or edit the RepositoryConfiguration object, you must have Debug and Security Administrator capabilities.

For more information, see the “Upgrade Issues” section of the Release Notes, and the Identity Manager Tuning, Troubleshooting, and Error Messages guide.

WorkItemTypes Configuration Object

This configuration object is defined in sample/workItemTypes.xml, which is imported by init.xml and update.xml. This object enumerates the supported work item type names, extensions, and display names.

The extends attribute allows for a hierarchy of work item types (workItem Types). When Identity Manager creates a work item, it delegates the work item to the specified users if its workItem type is:

• The type delegated

• One of the subordinate workItem types of the type being delegated

SystemConfiguration Object

The SystemConfiguration object provides a central control point for many system behaviors and provides a means of storing persistent customizations to system behavior. Given its importance, and the frequency with deployers customize it, the full range of possible customizations are not documented here. Some common customizations are documented here:

• Controlling the Display of the Password Confirmation Popup

• Configuring Delegate History List Length

• Enabling Attribute Value Customization

• Form and Workflow Save Behavior Customization

• Login-Related Customizations

• PasswordSync-Related Customizations

• Registering Scheduler Startup (for Clustered Environments)

• Source Adapter Task Customization

Controlling the Display of the Password Confirmation Popup

The forgotPasswordChangeResults attribute in the System Configuration object controls whether Identity Manager displays a confirmation page after a user or administrator has initiated a password change by clicking the Forgot My Password button during log in.

• The default value of forgotPasswordChangeResults.User is true.

• The default value of forgotPasswordChangeResults.Admin is false.

Configuring Delegate History List Length

The delegation.historyLength attribute controls the size of the list of both current and completed delegations displayed by the End User View workItem Delegation form. This attribute specifies the maximum number of delegations that can appear in the delegation table. Note that the table will show all current delegations, no matter which value you set here.

The SystemConfiguration object contains the security.delegation.historyLength attribute, which controls the number of previous delegations that are recorded.

Enabling Attribute Value Customization

The process.handleNativeChangeToAccountAttributes attribute controls the auditing of attribute values. When set to true, attribute value enabling is enabled for both the reconciliation process and for the provisioner. By default, this property is not enabled.

Form and Workflow Save Behavior Customization

The security.saveNoValidateAllowedFormsAndWorkflows attribute lists the IDs of forms and workflows that will be processed as a SaveNoValidate action. All other forms and workflows will be processed as a Save. If this list is not present, the behavior remains the same for all forms and workflows (all forms and workflows will be processed as SaveNoValidate.

Login-Related Customizations

You can customize login behavior by directly editing system configuration object attributes.

Enabling autocomplete for Login Pages

By default, Identity Manager prevents browsers from offering to store the user's credentials. You can enable the autocomplete feature for the login pages by changing the ui.web.disableAutocomplete system configuration object to true. The login pages include login.jsp, continueLogin.jsp, user/login.jsp, and user/continueLogin.jsp.

Identity Manager login forms other than the preceding ones are generated from XPRESS, and you must edit these forms to use the new display property. These forms, which reside in the sample directory, include this property commented out by default.

• Anonymous User Login

• Question Login Form

• End User Anonymous Enrollment Validation Form

• End User Anonymous Enrollment Completion Form

• Lookup Userid

Displaying an Error Message During an Attempt to Provision a Disabled User

The ProvisioningDisabledUserShouldThrow attribute controls whether Identity Manager will produce an error message when preventing an attempt to provision a disabled user. When set to true, Identity Manager will prevent any attempt to provision a disabled user to a resource and will produce an error. When this attribute is not set to true, then Identity Manager will still prevent the provisioning, but will not produce an error.

Launching the Password Login Workflow upon Login

The runPasswordLoginOnSuccess attribute controls whether Identity Manager will run the Password Login workflow when a user successfully logs in. When set to true, Identity Manager will run this workflow after successful login. By default, the value of this attribute is false.

PasswordSync-Related Customizations

You can customize PasswordSync behavior by directly editing the following system configuration object attributes:

• PasswordSyncResourceExcludeList – This attribute controls whether lists of resource names should always be excluded from synchronization.

• PasswordSyncThreshold – If PasswordSync is enabled for a resource for which Identity Manager can also initiate password changes, you can use this setting to prevent a loop-back password change. When you initiate a password change from Identity Manager, it will set the password on the resource, and the PasswordSync library will notify Identity Manager of the change. Identity Manager will then compare the lastPasswordDate on the user object to the current time. If this difference is less than the PasswordSyncThreshold, Identity Manager will ignore the password change.

Registering Scheduler Startup (for Clustered Environments)

The scheduler.hosts attribute registers startup behavior for the scheduler for each Identity Manager application instance.

The value of scheduler.hosts is a map that contains an entry for each host that you want to control. The key is the hostname for the Identity Manager application instance.

To see the hostname value, go to the debug/GetStatus.jsp page in your Identity Manager installation.

The following values are valid:

• enabled (default)

• disabled

• manual (suspended)

The default value is used if no value or an invalid value is specified.

The task.scheduler.enabled and task.scheduler.suspended properties in the Waveset.properties file override the value set in the System Configuration object.

Following is an example of the scheduler attribute from Configuration:System Configuration:

<Attribute name=’scheduler’>
   <Object>
      <Attribute name=’hosts’>
         <Map>
            <MapEntry key=’goliad’ value=’enabled’/>
            <MapEntry key=’sanjacinto’ value=’manual’/>
            <MapEntry key=’washington’ value=’disabled’/>
         </Map>
      </Attribute>
   </Object>
</Attribute>

Source Adapter Task Customization

You can edit the following two attributes to customize the behavior of the source adapter task:

• sources.subject – Specifies the login name of the administrator designated as the owner of the source adapter task.

• sources.hosts – Specifies the server on which the source adapter task runs.

Role Configuration Object

The Role Configuration object defines the supported Role Types, Actions, and List Columns. The following sections describe the supported elements of a Role Type definition:

• Types Attribute

• Actions Attribute

• List Columns Attribute

• Other Options

Types Attribute

Role type attributes are configured in the types section of the Role Configuration object. For each type of role in the list, for example business or IT roles, you must specify the following attributes:

• displayName Attribute

• authType Attribute

• workItemTypes Attribute

• features Attribute

displayName Attribute

Specifies the type’s display name whose value is a message catalog key.

authType Attribute

Specifies the authorization type associated with the role type. An authorization type enables fine-grain authorization for who is allowed to view and manage this role type. If you have not yet defined an authType, add one to the AuthorizationTypes configuration object. You must reference that authType within an AdminGroup (capability) as a type within a Permission that grants access to roles of this authType.

All roles have an authorization type. If you load a role without an authorization type, the authorization type defaults to ITRole.

workItemTypes Attribute

The type of work items that can be created for role assignment approval and role change approval. If you have not yet defined the specified workItem types, add them to the WorkItemTypes configuration object.

features Attribute

The features attribute includes the following features:

• changeApproval. If specified, indicates that Owners specified in the Role must approve any changes to a Role of this type. If no Owners are specified, then no approvals occur.

• changeNotification. If specified, indicates that any changes to a Role of this type will send email notifications to the owners of the specified Role.

• containedTypes. Required feature whose value is the list of Role types that can be contained in this type, where the allowed values are:

  • BusinessRole

  • ITRole

  • ApplicationRole

  • AssetRole

  • Custom role types

• assignResources. If specified, indicates that resources and resource groups can be assigned to roles of this type. If not specified, defaults to no Resources can be assigned to Roles of this type.

• userAssignment. If specified, indicates whether Roles of this type can be directly assigned to Users. If this Role type can be assigned directly to Users, this feature also specifies whether the Users can be assigned manually and automatically. If not specified, defaults to user assignment not allowed.

  ---

  Note –

  Automatic assignment is not supported in this release, but will be in a future release.

  ---

• manual. If specified (for example true or false), indicates whether you can manually assign Roles of this type to Users.

  • activateDate. If specified (for example true or false), indicates whether you can specify a future activation (start) date for Roles of this type when assigned to a User. Note that this feature is valid only if userAssignment.manual is true.

  • deactivateDate. If specified (for example true or false), indicates whether you can specify a future deactivation (end) date for Roles of this type when assigned to a User. Note that this feature is valid only if userAssignment.manual is true.

  ---

  Note –

  You can set both activateDate and deactivateDate to true, even if userAssignment.manual is not. If you set both attributes to true for a roleType, and if the role is contained by another role optionally, then you can specify activate and deactivate dates when assigning the optional role to a user.

  ---

• roleExclusions. If specified, indicates that Roles of this type allow the Role editor to specify a list of Roles that cannot be assigned to a user if this Role is assigned; an exclusion list.

Actions Attribute

The Actions attribute defines a set of actions that a Role administrator can take on one or more Roles in the list Roles table and when adding role exclusions to contained roles to an existing role.

Three sets of actions are specified in role configuration:

• actions. Actions displayed in the main role list and on the Find Role Results pages.

• addContainedRoleActions. Actions displayed as an administrator is adding contained roles to a role.

• addRoleExclusionsActions. Actions displayed as an administrator is adding a role exclusion to a role.

Each action is defined with the following attributes:

• action. Specifies the command.

• label. Specifies the display name message key.

• requiredPermissions. Permissions that control whether the action is displayed, depending on the administrator’s permissions.

  • Type. Type of object to which an administrator must have the given rights.

  • Rights. List of rights that an administrator must have for the given object type

• selectionRequired. Indicates that a role must be selected for this action.

• type. Specifies the role action type, which can be create, update, delete, or task.

• view. Copies the contents of this attribute onto the role view during the execution of the action for create, update, and delete role action types.

• task. Specifies the task to launch for task action types.

• skipTaskLaunchForm. If set to true, skips the task launch form. Otherwise the task launch form (if present) is displayed. Applies to task action types.

List Columns Attribute

The List Columns attribute defines the set of attribute names and labels to display as column headings when viewing lists of Roles (for example, List roles and find role results).

You can specify unique sets of attributes to display as list column headings. The attributes for each defined column are

• name. Name of the role attribute to display

• displayName. Display name to appear in the column header

• rule. Optional rule that might format the attribute value. The rule is invoked for each row in the list, and the value returned by the rule is what displays in each table cell.

Other Options

You can also set the following options in the Role Configuration object:

• roleListMaxRows. The maximum number or roles to list

• roleListPageSize. The number of roles to display on a single page

End User Tasks Object

The End User Tasks object defines the tasks that you can run from the Identity Manager user interface. You can assign the EndUserTask authorization type to any TaskDefinition object, and you can assign the EndUserRule authorization type to any Rule objects that must be exposed.

Refreshing User Objects

Certain types of changes require an administrator to refresh all User objects. For example, you must refresh all User objects when you change the inline attributes for Type.USER in RepositoryConfiguration. Whenever you mark an attribute as queryable or summary in the IDMSchemaConfiguration object, you must refresh all User objects for the change to affect older, unmodified objects. The same logic applies when a new version of Identity Manager adds a new attribute, or when a new version of Identity Manager changes the values of an existing attribute. The upgrade process or an administrator must refresh all User objects for the change to affect older, unmodified objects.

There are three ways to re-serialize existing users:

• Modify an individual User object during normal operations.

  For example, opening a user account through the user interface and saving it with or without modifications.

  Disadvantage: This method is time-consuming, and the administrator must be meticulous to ensure all existing users are re-serialized.

• Use the lh refreshType utility to re-serialize all users. The refreshType utility’s output is a refreshed list of users.

  lh console
  refreshType User

  Disadvantage: Because the refreshType utility runs in the foreground and not the background, this process can be time-consuming. If you have a lot of users, re-serializing them all takes a long time.

• Use the Deferred Task Scanner.

Before running the Deferred Task Scanner process, you must edit the System Configuration object using the Identity Manager IDE or some other method.

Search for ’refreshOfType’ and remove the attributes for ’2005Q4M3refreshOfTypeUserIsComplete’ and ’2005Q4M3refreshOfTypeUserUpperBound’.

After editing the System Configuration object, you must import that object to repository for your changes to be present.

Disadvantage: This method causes the next Deferred Task Scanner run to take a long time because it examines and rewrites almost every User object. However, subsequent Deferred Task Scanner runs should execute at normal speed and duration.