Oracle Waveset Service Provider 8.1.1 Deployment

Chapter 4 IDMXUser View

The IDMXUser view is similar in structure to the Waveset user view, though attribute names have been changed to make it less specific to users and accounts. Instead of referring to the term “user”, this discussion will use the terms “composite object” or “master object” The term “linked object” will be used instead of “account.”

Refer to the Javadocs and the sample Java file (ApiUsage.java) in the REF kit for more details about the IDMXUser view.

Implementing the IDMXUser View

Manipulation of directory users is usually performed through the IDMXUser view rather than with the persistent object methods. The primary difference is that the view supports provisioning operations, while the persistent object methods simply modify the data stored in the directory.

The general process for using a view is as follows:

Create or check out a view, which is represented in memory as a GenericObject.
Make changes to the attributes in the view.
Check in the view. The system might need to perform complex actions as a result of the changes, including provisioning accounts and updating the directory.

See Deployment Guide for more information about implementing views

IDMXUser View Reference

Attributes in the IDMXUser view are divided into the following categories:

Account attributes are values that are actually stored in a resource account or in the directory. They are defined by the schema map of a Resource definition, and are the attributes you most often modify when creating or editing accounts.

Commonly used account attributes include accountId, password, email, and fullname.
System attributes are values defined by the Service Provider system, but are independent of resource type, and not necessarily stored on the resource or in the directory. They are used to request certain operations, or store information that cannot be represented with native account attributes. System attributes are collected under a top-level attribute named sys to avoid name conflicts with account attributes.

Commonly used system attributes include sys.identity , sys.links, sys.delete, and sys.expirePassword.

A subcategory of system attributes are called action attributes. An action attribute is set to the value true to indicate that a special operation is to be performed when the view is checked in. For example, setting the action attribute sys.delete requests that an account be deleted.
Policy attributes are values that reflect the indicate how the account has been affected by the Service Provider Account Policy, which is configured on the main Service Provider configuration page of the Administrator Interface. An account lockout occurs in Service Provider when a user has too many consecutive failed login attempts.
Runtime attributes are values that exist only in the view and are never stored on the resource. Some runtime attributes contain information derived from the resource definitions which may assist the application in configuring the user interface. Other runtime attributes may contain state related to UI technologies such as Waveset forms. Finally, the application may store arbitrary attributes in the view provided the names do not conflict with other attributes.

Commonly used runtime attributes include display, info, and command.

Top-Level Attributes

The following table lists the system defined top-level attributes of the view.

Attribute	Description
sys	An object containing internal system attributes related to the composite object. This is functionally similar to the `waveset` attribute in the Waveset user view, except that there are fewer items that can be modified. Many of the attributes in this object are action attributes, meaning that they are NOT stored, but setting them causes the check-in to perform certain actions.
info	An object containing metadata about all of the objects linked to the composite object. This is functionally similar to the `accountInfo` attribute in the Waveset User view. This object is read-only.
objects	An list of objects containing the attributes of accounts linked to the directory user. This is functionally similar to the `accounts` list in the Waveset User view.
display	An object containing Generic Edit Form state. This is set only if you are using Waveset XML forms.
command	The command posted to the Generic Edit Form processor. This is set only if you are using Waveset XML forms.
policy	Policy-related attributes. See policy Attributes for more information.

Unlike the Waveset User view, the primary attributes of the composite object will be stored as top-level attributes of the view, rather then nested in waveset or accounts[Lighthouse]. The schema of the composite is variable, though the following attributes will always exist.

Attribute	Description
name	The unique object name. For objects in directories, this is normally the `uid` not the full DN. For accounts, this is the name that the user would use to login.
password	The password if this object represents an account. When the view is fetched, this will not have the current password. It may be set by the application to change the password.
resources	A list of Resource object names representing the assigned resources.
applications	A list of Application object names representing the assigned applications. This is the same as what Waveset refers to as “Resource Groups” in the user interface.
roles	A list of Role object names representing the assigned roles.

In addition to the standard attributes, the following attributes will usually be defined in the composite object schema if the object represents a user account.

firstname
lastname
fullname
email

sys Attributes

The sys attribute retrieves and sets system characteristics. The following table defines the attributes currently defined under the sys attribute. The attribute will be shown as paths from the root of the view.

Action attributes do not have a value when checked out. An asterisk refers to the name of a resource. An attribute such as sys.links[*].name would be expanded to a value such as sys.links[HR Database].name .

Attribute	Description
sys.identity	The full native identity of the object. For directory objects, this will be the DN. When creating new objects, this will override the identity template defined in the Resource. For existing objects, it must not be changed.
sys.delete	An action attribute that may be set to `true` to indicate that this object should be deleted.
sys.disable	An action attribute that may be set to `true` to disable an account. If it is set to `false`, then the account is enabled. This is an action-only attribute. When the view is checked out, the attribute will not have a value.
sys.newIdentity	An action attribute that may be set to another object identity to indicate that the object should be renamed. Not all resources support changing identities.
sys.resetPassword	An action attribute that may be set to `true` to indicate that the password should be reset.
sys.expirePassword	An action attribute that may be set to `true` to indicate that the password should be expired.
sys.form	The name of the form used to display or process this view, set only when Waveset XML forms are being used.
sys.noDefaultForm	An action attribute that may be set to true to prevent any default user form from being used.
sys.links	A list of objects holding information about the objects linked to the composite. This is functionally equal to the waveset.accounts in the user view.
sys.lock	If this boolean action is set to `true`, then when the IDMXUser view is checked-in (or refreshed), then the IDMXUserViewer will run the “Lock Account Rule” to set the appropriate values in the view to lock the account. If this rule is not specified in the configuration and sys.lock is `true`, an exception is thrown.
sys.locked	Set to true if the account has been locked explicitly or due to too many failed login attempts. The IDMXUserViewer runs the “Is Account Locked Rule” to determine if the account is locked.
sys.unlock	If this boolean action is set to `true`, then when the IDMXUser view is checked-in (or refreshed), the IDMXUserViewer will run the “Unlock Account Rule” to set the appropriate values in the view to unlock the account. If this rule is not specified in the configuration and sys.lock is `true`, an exception is thrown.
sys.targets	A list of resources, services, or applications that should be targeted on the check-in. The list can include the Resource, Service, or Application PersistentObjects themselves, or more usefully just their names. If no targets are specified, then the provisioner will provision to all assigned resources, service, and applications.
sys.links[*].name	A unique name used to identify the linked object in the view. Usually this is the same as the name of the Resource containing the linked object, but may be qualified if there is more than one linked object from this Resource.
sys.links[*].resource	The name of the Resource containing the linked object. Often the same as sys.links[*].name, but not necessarily.
sys.links[*].type	The type of the Resource containing the linked object.
sys.links[*].identity	The full native identify of the object. For directory objects, this will be the DN.
sys.links[*].created	Set to `true` if the object is believed to exist.
sys.links[*].disabled	Set to `true` if the object is currently disabled.
sys.links[*].locked	Set to `true` if the object is currently locked.
sys.links[*].fetched	Set to `true` if the current attributes of the object have been fetched.
sys.links[*].attributes	An object containing last known attribute values of the linked object. This will be set only when the application requests that the current values be fetched. They are not stored permanently in the composite.
sys.txn.waitForFirstAttempt	This attribute dictates how control returns to the caller when an IDMXUser view object is checked in. If set to `true`, the check-in operation will block until the provisioning transaction has completed a single attempt. If set to `false`, the check-in operation will return control to the caller before attempting the provisioning transaction. It is recommended to enable this option. If asynchronous processing is disabled, then the transaction will have either succeeded or failed when control is returned. If asynchronous processing is enabled, then the transaction will continue to be retried in the background.
sys.txn.enableAsynchronous	This attribute controls whether processing of provisioning transactions continues after the check-in call returns. Since only a single attempt will be made synchronously, this option must be enabled if retrying transactions is desired.
sys.txn.asynchronousMS	An upper bound expressed in milliseconds of how long the server will retry a failed provisioning transaction. This setting complements the retry settings on the individual resources, including the master LDAP directory. For example, if this limit is reached before the resource retry limits are reached, the transaction will be aborted. If the value is negative, then the number of retries is only limited by the settings of the individual resources.
sys.txn.persistImmediately	If set to `true`, provisioning transactions will be written to the Transaction Persistent Store before they are attempted. Enabling this option might incur unnecessary overhead since most provisioning transactions will succeed on the first attempt. It is recommended to disable this option unless the waitForFirstAttempt attribute is disabled.
sys.txn.persistOnAsync	If set to `true`, provisioning transactions will be written to the Transaction Persistent Store before they are processed asynchronously. If the waitForFirstAttempt attribute is enabled, then transactions that need to be retried will be persisted before control is returned to the caller. If the waitForFirstAttempt attribute is disabled, then transactions will always be persisted before they are attempted. It is recommended to enable this option.
sys.txn.persistOnEachUpdate	If set to `true`, provisioning transactions will be persisted after each retry attempt.

The sys.txn attributes correspond to fields displayed on the Default Transaction Execution Options section of the Edit Transaction Configuration page of the Administrator Interface. This page sets the values globally.

The global values can be overridden in a user form as follows.

<Field name=’sys.txn.persistImmediately’/>
   <Default>
      <s>true</s>
   </Default>
</Field>

objects Attributes

The objects attribute contains a list of objects, each holding the editable attributes of the linked objects. It is similar to the accounts attribute in the Waveset User view. Like the Waveset User view, the attributes in each object are mostly arbitrary and defined by the Resource schema. The following attributes are defined by the system and will always exist.

Attribute	Description
objects[*].name	A unique name used to identify the linked object in the view. Usually this is the same as the name of the Resource containing the linked object, but may be qualified if there is more than one linked object from this Resource. This name may be used to locate an object in the info attribute.
objects[*].password	May be used to set the password for accounts that support passwords. This value will initially be null for new accounts. When editing existing accounts, it will be non-null to indicate that a password has been set, but the value will not be the actual password.
objects[*].locked	Initially set to true if the linked object is an account and has been locked. May be changed to change the lock status of the account. This attribute is valid only if the associated resource supports account locking. To unlock a locked account, you must explicitly set this value to the string `false` . If you leave the value null, the current lock status will not be changed.
objects[*].sys.identity	The full native identity of the object. For directory objects, this will be the DN. When creating new objects, this will override the identity template defined in the Resource. For existing objects, it must not be changed.
objects[*].sys.delete	An action attribute that may be set to `true` to indicate that this object should be deleted.
objects[*].sys.disable	An action attribute that may be set to `true` to disable an account. If it is set to `false`, then the account is enabled. This is an action-only attribute. When the view is checked out, the attribute will not have a value.
objects[*].sys.resetPassword	An action attribute that may be set to true to trigger a password reset. This will result in a randomly generated password being assigned.
objects[*].sys.expirePassword	An action attribute that may be set to `true` to indicate that the password should be expired.
objects[*].sys.unlink	An action attribute that may be set to `true` to indicate that this object should be unlinked.
objects[*].sys.newIdentity	An action attribute that may be set to another object identity to indicate that the object should be renamed. Not all resources may support identity changes.

info Attributes

The info attribute contains metadata about the objects liked to this composite. It currently does not have much, but will evolve to contain information similar to that in the accountInfo attribute of the Waveset User view. There will however be much more control over the amount of information included.

Attribute	Description
info.resourceTypes	A list of resource type names for all resources assigned to this user.

policy Attributes

Account lockout occurs when a user has too many consecutive failed login attempts. This applies to both password-based login attempts and login attempts based on authentication questions. Separate limits for password-based and question-based account lockout are specified on the “Account Policy” section on the main configuration page. Accounts that are locked out can be explicitly unlocked by an administrator or implicitly when the lock expires, such as after one hour.

Since locking out accounts is LDAP-vendor specific, Service Provider allows you to configure rules that operate on the IDMXUser view to determine if an account is locked out, to update the view to lock an account, and to update the view to unlock an account.

The policy.questions[*] attributes will not be included in the IDMXUser view or updated unless the buildAuthQuestions option is set in the form.

Attribute	Description
policy.failedPasswordLoginAttemptsCount	The number of consecutive password-based failed login attempts. When the user logs in successfully (either with a password or authentication questions), this value is reset. If this value is not present, it is assumed to be zero. (integer: read-only)
policy.failedQuestionLoginAttemptsCount	The number of consecutive authentication question-based failed login attempts. When the user logs in successfully (either with a password or authentication questions), this value is reset. If this value is not present, it is assumed to be zero. (integer: read-only)
policy.questions[*].id	The unique identifier that is used to associate this question with one defined in the policy. This is a read-only attribute.
policy.questions[*].question	The question text, which can be displayed to the user. This attribute is read-only.
policy.questions[*].answer	The user’s answer for the question, if specified.
policy.questions[*].loginInterface	The login interface with which this policy question is associated. Its value is a unique message catalog key for each loginInterface.

IDMXUser View Differences

The following sections provide a summary of the differences between the IDMXUser view, and views defined in Oracle Waveset.

Oracle Waveset User View

Top-Level Attributes

Waveset User View	IDMXUser View
password	Not applicable
global	Not applicable
update	Not applicable

waveset Attributes

Waveset User View	IDMXUser View
waveset.form	sys.form
waveset.id	sys.id
waveset.accountId	accountId (actual attribute name is name assigned in the schema map)
waveset.password	password (actual attribute name is assigned in the schema map)
waveset.email	email (actual name is assigned in the schema map)
waveset.disabled	Not applicable
waveset.roles	roles
waveset.resources	resources
waveset.policies	policy
waveset.applications	applications
waveset.organization	Not applicable
waveset.organizationId	Not applicable
waveset.policies	Not applicable
waveset.adminRoles	Not applicable
waveset.capabilities	Not applicable
waveset.creator	Not applicable
waveset.createDate	Not applicable
waveset.lastModifier	Not applicable
waveset.lastModDate	Not applicable
waveset.backgroundSave	Not applicable
waveset.attributes	Not applicable
waveset.original	Not applicable

waveset.accounts Attributes

Waveset User View	IDMXUser View
waveset.accounts	sys.links
waveset.accounts[].resource	sys.links[].resource
waveset.accounts[].id	Not applicable
waveset.accounts[].accountId	sys.links[].identity
waveset.accounts[].accountGUID	sys.links[].guid
waveset.accounts[].accountDisplayName	sys.links[].displayName
waveset.accounts[].tempId	Not applicable
waveset.accounts[].created	sys.links[].created
waveset.accounts[].disabled	sys.links[].disabled
waveset.accounts[].attributes	sys.links[].attributes
waveset.accounts[].password	sys.links[].attributes.password
waveset.accounts[].resourceAttributes	Not applicable
waveset.accounts[].properties	Not applicable
waveset.accounts[].templateParameters	Not applicable

accounts Attributes

Waveset User View	IDMXUser View
accounts[]	objects[]
accounts[].identity	objects[].sys.identity
accounts[].UserDefined	objects[].UserDefined
accounts[Lighthouse].firstname	firstname (attribute name assigned in schema map)
accounts[Lighthouse].lastname	lastname (attribute name assigned in schema map)
accounts[Lighthouse].fullname	fullname (attribute name assigned in schema map)
accounts[Lighthouse].UserDefined	UserDefined

accountInfo Attributes

Waveset User View	IDMXUser View
accountInfo	info
accountInfo.typeNames	info.resourceTypes
accountInfo.types	Not applicable
accountInfo.accounts	info.objects
accountInfo.accounts[Lighthouse]	info.master

resourceAccounts View

Waveset User View	IDMXUser View
selectAll	Not applicable
resourceAccounts.currentResourceAccounts	objects
resourceAccounts.tobeCreatedResourceAccounts	info.objects
resourceAccounts.tobeDeletedResourceAccounts	info.objects
resourceAccounts.currentResourceAccounts[].attributes	objects[]
resourceAccounts.currentResourceAccounts[].selected	Not applicable

Note –

The mappings for info.objects are functionally similar to their resource accounts views counterparts, but they are not structurally similar.

In general, in Waveset, the resource accounts views operate by setting the selected attribute in the currentResourceAccounts list to true, which will then have different behavior for each view type.

In Service Provider, accounts are not selected with a boolean attribute. Instead, each operation has an action attribute that is initially null, and when set, triggers the operation.

All resource accounts views provide a way to update arbitrary account attributes in addition to performing an operation.

Most allow attributes to be placed in:

resourceAccounts.currentResourceAccounts[].attributes

The Rename view uses:

accounts[]

In the IDMXUser view, you always place attributes you want to modify in:

objects[]

password View

The desired password is simply set in the following attributes:

password
objects[].password

There is no automatic synchronization of passwords from the top level password attribute to the password attribute on the individual resource accounts. To pre-expire the password, set the following attributes:

sys.expirePassword
objects[].sys.expirePassword

Disable and Enable Views

In Waveset, accounts are enabled or disabled by checking out the Enable or Disable view and setting the value of

resourceAccounts.currentResourceAccounts[].selected to true.

In the IDMXUser view, you set the following action attributes to true or false.

sys.disable
objects[].sys.disable

Rename View

In the Waveset Rename view, the new name is specified in the top-level field newAccountId, which is then propagated to those resource accounts selected in the currentResourceAccounts list. In the IDMXUser view, renames are requested by setting the following attributes to the desired identity, which for LDAP resources must be the full DN.

sys.newIdentity
objects[].sys.newIdentity

Deprovision View

The Waveset deprovision view has a complex structure designed for use with interactive forms. The three operations that may be requested through this view are:

unassign. Removes the assignment and deletes the account.

unlink. Removes the account link without deleting.

delete. Deletes the account, but leave the assignment.

In the IDMXUser view, you perform an unassign simply by removing a name from the roles, resources, or applications lists.

To perform an unlink, you may remove an object from the sys.links list, or set the following action attribute to true:

objects[].sys.unlink

To perform a delete without unassigning set the following command attribute to true.

objects[].sys.delete

To delete the directory user, set the following attribute to true:

sys.delete