Previous      Contents      Index      Next
Sun[TM] Identity Manager 8.0 Deployment Overview

Appendix A  
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:

Note	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 UserView, PasswordView, etc.).

Object Naming Conventions

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

Character	Description
'	single quotation mark
=	equal sign
.	period
|	vertical bar
[	left bracket
]	right bright
,	comma
:	colon
$	dollar sign
\	backslash
"	double quotation mark

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

Character	Description
_	underscore
%	percent sign
*	asterisk
#	number sign
^	caret

---

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 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 Integrated Development Environment (Identity Manager IDE) are 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

Note	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>

Note	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.

Note	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

Note	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 multivalued, 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.

Figure A-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'/>Configuration list/read/write. <IDMObjectClassAttributeConfiguration name='lastname' queryable='true' summary='true'/> <IDMObjectClassAttributeConfiguration name='fullname'/> ... </IDMObjectClassConfiguration> </IDMObjectClassConfigurations> </IDMSchemaConfiguration> </Configuration> </Waveset>

Note	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 ObjectClass

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

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

Note	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.

SummaryAttrRoleCountLimit

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' ... >

Caution	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).

Note	If you change the inline attributes for Type.USER, you must refresh all User objects. For more information, see Refreshing User Objects.

Note	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.

t

Table A-1  workItem Types  

Type	extends	Display Name
workItem	none	All Work Items
approval	workitem	Approval
organizationApproval	approval	Organization Approval
resourceApproval	approval	Resource Approval
roleApproval	approval	Role Approval
roleChangeApproval	approval	Role Change Approval
applicationRoleApproval	roleApproval	Application Approval
applicationRoleChangeApproval	roleChangeApproval	Application Change Approval
assetRoleApproval	roleApproval	Asset Approval
assetRoleChangeApproval	roleChangeApproval	Asset Change Approval
businessRoleApproval	roleApproval	Business Role Approval
businessRoleChangeApproval	roleChangeApproval	Business Role Change Approval
itRoleApproval	roleApproval	IT Role Approval
itRoleChangeApproval	roleChangeApproval	IT Role Change Approval
attestation	workItem	Access Review Attestation
accessReviewRemediation	workItem	Access
review	workItem	Remediation

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, we do not document the full range of possible customizations here. Some common customizations are documented here.

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.

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.

Note	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.

Note	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>

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
Actions
List Columns

Types

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
authType
workItemTypes
features

displayName

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

authType

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.

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

workItemTypes

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

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 ResourceGroups 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

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

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 reserialize 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 reserialized.

Use the lh refreshType utility to reserialize 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, reserializing them all takes a long time.

Use the Deferred Task Scanner.

Note	Before running the Deferred Task Scanner process, you must edit the System Configuration object using the Identity Manager Integrated Development Environment (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.

Previous      Contents      Index      Next

---

Part No: 820-2961-10.   Copyright 2008 Sun Microsystems, Inc. All rights reserved.