Chapter 5 Other Objects in Service Provider

This chapter describes how the following objects differ between Waveset and Service Provider:

• Service Provider User Forms

• Account and Password Policies

• Rules

• Resources

• Workflow Callouts

• Delegated Administration

Service Provider User Forms

All user forms that access account information for Service Provider accounts must use the IDMXUser view to reference attributes on their Service Provider Directory account and linked resource accounts.

If you create your own user form, and the form is to be displayed as an option on the Edit Main Configuration page of the Administrator Interface, the authType Configuration attribute must be assigned the value SPEUserForm. Otherwise, this attribute may be omitted. Service Provider user forms operate on the IDMXUser view instead of the Oracle Waveset User view. Therefore, a different authType is useful for distinguishing between the forms.

The following example illustrates the use of the authType attribute.

<Configuration authType=’SPEUserForm’ wstype=’UserForm’ name=’My Service Provier User Form’>

The Edit Main Configuration page of the Administrator Interface allows an administrator to select a default End User, Administrator, and Synchronization user form. If no End User or Synchronization user form is defined in the Administrator Interface, then no form will be used, unless a form is specified in the sys.form attribute in the IDMXUser view. If a default Administrator user form is not selected, then delegated administrators will not be able to create or edit accounts from the Administrator Interface. However, if the sys.noDefaultForm attribute is set to true in the IDMXUser view, the default user form specified in the Administrator Interface will not be used.

End User Form

The end user form is typically a simple form that defines a few fields and possibly provides default values. The display.session and display.speContext attributes should not be called, because the results are not displayed on the Administrator Interface.

Administrator User Form

The administrator user form determines what is displayed on the Create or Edit Service Provider Users page. This form will typically be more complex than the end user form, as it can be used to perform tasks such as retrieving lists of available resources and determining which attributes can be edited.

Synchronization User Form

The Service Provider Synchronization task uses the synchronization form to process accounts. This task ensures that account changes on one resource are propagated to other resources, including the LDAP master directory.

The Synchronization user form performs the same general functions as an Waveset Active Sync user form. It translates an arbitrary set of incoming account attributes into the IDMXUser view. See Active Sync User Forms for more information.

Account and Password Policies

Service Provider account and password policies behave differently than those for Oracle Waveset:

• There can be only one account policy defined for the entire Service Provider user population. This policy can be set on the main Service Provider configuration page.

• The Service Provider account policy does not support the following options that are available for Oracle Waveset users

  • Expires in

  • Warning time before expiration

  • Reset Option

  • Reset temporary password expires in

  • Reset Notification Option

  • Passwords may be changed or reset

  • Enforce Answer Policy at Login

  • Allow User Supplied Questions

    These options are not displayed when editing the Service Provider Policy object.

  The Service Provider account policy can refer to an accountId and a password policy. Service Provider does not maintain the password history. Password policies, however, allow setting the Number of Previous Passwords that Cannot be Reused and Maximum Number of Similar Characters from Previous Passwords that Cannot be Reused options. These options are ignored by Service Provider.

• Account lockout in Service Provider 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.

• The sample account policy Service Provider Policy sets separate limits for password-based and question-based account lockouts. Accounts that are locked out can be explicitly unlocked by an administrator or implicitly when the lock expires (such as after one hour).

Rules

Because the mechanism for locking out accounts varies for each LDAP vendor, 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. These rules are selected on the Edit Main Configuration page.

Is Account Locked Rule

The rule selected as the “Is Account Locked Rule” determines if an account is locked. The full IDMXUser view is available to this rule. The rule takes the following arguments:

• maxFailedPasswordLogins — An integer declaring the maximum number of failed password logins before an account is locked according to the Service Provider System Account Policy.

• maxFailedQuestionLogins — An integer declaring the maximum number of failed question logins before an account is locked according to the Service Provider System Account Policy.

The rule should return true only if the account is locked.

The sample rule “Service Provider Example Is Account Locked Rule” operates on Sun Java System Directory Server 5.x. This rule expects that the accountUnlockTime and passwordRetryCount account attributes are defined in the LDAP resource schema map.

Lock Account Rule

The rule selected as the “Lock Account Rule” sets attributes in the IDMXUser view that cause an account to be locked. The full IDMXUser view is available to this rule. In addition, it takes the following argument:

lockExpirationDate: A possibly null java.util.Date at which the lock should expire.

This rule should update the IDMXUser view so that the LDAP account will be locked when the view is checked in.

The sample rule “Service Provider Example Lock Account Rule” on Sun Java System Directory Server 5.x. This sample rule expects that the accountUnlockTime and passwordRetryCount account attributes are defined in the LDAP resource schema map.

Unlock Account Rule

The rule selected as the “Unlock Account Rule” on the main configuration page sets attributes in the IDMXUser view that cause an account to be unlocked. The full IDMXUser view is available to this rule. The rule takes no additional arguments.

This rule should update the IDMXUser view so that the LDAP account will be unlocked when the view is checked in.

The sample rule “Service Provider Example Unlock Account Rule” operates on Sun Java System Directory Server 5.x. This rule expects that the accountUnlockTime and passwordRetryCount account attributes are defined in the LDAP resource schema map.

Resources

Note the following items when creating and configuring resources for use with Service Provider:

• You must configure the user directory as a resource. The directory can be maintained from the Service Provider Configuration pages in the Administrator Interface.

• Any resources that are to be synchronized with the user directory should be configured from the Edit Synchronization Policy resource action, and configured for the target object type “Service Provider User.”

• Service Provider stores all of its meta information in the LDAP attribute mapped to xml in the resource definition schema map. (For example, jpegPhoto) The size of the data stored in this attribute is usually small (<1KB) but can be larger, depending on the number of resources assigned to the user.

  If the Retro Changelog is enabled in your Sun Java System Directory Server, add the attribute that corresponds to the xml LDAP attribute (for example, jpegPhoto) to the list of ignore_attributes in the Retro Changelog plugin’s configuration. This can be accomplished by using the Directory Server administration console.

The default user form and rules associated with each resource might need to be customized to work with Service Provider. See the following sections for more details:

• Active Sync User Forms

• Rules

Active Sync User Forms

The following list describes the differences between user forms in Waveset and Service Provider:

• In Waveset, both the Synchronization Input form and the default user form are processed. In Service Provider, only the Synchronization Input form is processed.

• The IDMXUser view is used instead of a User view. See Chapter 4, IDMXUser View for more information.

• In both Waveset and Service Provider, all of the attributes received are placed under the activeSync top-level attribute.

• Waveset also sets the following attributes to contain information about the resource definition itself:

  activeSync.resourceName
  activeSync.resourceId
  activeSync.resource

  Other attributes are culled from the resource. Service Provider does not set these.

Rules

The nature of the following rules varies in Service Provider:

• Correlation rules

• Confirmation rules

• Delete Rules

Correlation Rule

Because reconciliation is not performed on a Service Provider resource, a correlation rule is invoked on-demand to discover existing account information.

In the Waveset User view, the account attribute may contain numerous account attributes. In the IDMXUser view, these account attributes are defined at the top-level of the view. For example, in Waveset, a correlation rule might make a reference to <ref>account.accountId</ref> . In Service Provider, the reference would simply be <ref>accountId</ref> .

Confirmation Rules

A Waveset confirmation rule may reference the following attributes:

account — The attributes from the Active Sync account

user — The User view

A Service Provider confirmation rule sets the same attributes, but the contents of the user attribute contains only the user attributes stored in the directory. It will not contain a full IDMXUser view.

Delete Rule

An Waveset delete rule may reference the following attributes:

activeSync — The attributes from the Active Sync account

account — Identical to activeSync.

In a Service Provider delete rule, the Active Sync account attributes are at top-level. They are not wrapped in either activeSync or account.

Link Correlation Rule

The linkTargets IDMXUser view option allows the caller to specify the list of resources that should be targeted for linking. When using forms, the list can be provided as a form property with the same name. Form properties are assimilated into view options when the IDMXUser view is checked in.

A link correlation rule selects resource accounts that the user might own. Given the view of the user, a link correlation rule returns an identity, a list of identities, or an option map.

If the rule returns an option map, then the view handler uses the map to look for resource accounts and obtains a list of identities that satisfy these options. For example, the searchFilter option of the getResourceObjects FormUtil method can be used to pass a search filter to an LDAP resource adapter.

A link correlation rule must have the authType attribute set to SPERule with the subtype set to SUBTYPE_SPE_LINK_CORRELATION_RULE.

Link Confirmation Rule

A link confirmation rule eliminates any resource accounts from the list of potential accounts that the link correlation rule selects. Given the view of the user and the list of candidate resource accounts, a link confirmation rule selects at most one resource account from the candidate list. The view of the user is visible under the ’view’ path, while the list of candidates is available under the ’candidates’ path.

If the link correlation rule selects no more than one resource account, the link confirmation rule is optional.

---

Note –

Unlike Waveset confirmation rules , a link confirmation rule is invoked only once during the linking process.

---

A link confirmation rule must have the authType attribute set to SPERule with the subtype set to SUBTYPE_SPE_LINK_CONFIRMATION_RULE.

Workflow Callouts

Service Provider does not support workflows. However, workflow callouts can be implemented.

Workflow callouts enable the execution of custom code before and/or after a Service Provider transaction is processed. A pre-operation callout is executed before, while the post-operation callout is executed after a transaction is processed.

Callouts are registered with the Service Provider main configuration object in the workflowCallout.callouts attribute. The key in the workflowCallout.callouts map must be the name of the registered callout, while the value is the class implementing the callout. Registered callouts can be selected on the Service Provider configuration page of the Administrator interface for invocation in both the pre- and post-operation stages and for each transaction type.

Use the IDMXUserViewer to override the system-wide callout settings. By setting the preOpCallout or postOpCallout view options to the name of the callout, the system-wide callout settings can be overridden.

Callouts return any of the following values: success, failure or pending. The pending result is returned if the callout requires more time to process the transaction, such as a manual interaction. Callouts returning a pending result can resume transactions later. The following table summarizes how Service Provider proceeds in each of the possible scenarios.

	Success	Failure	Pending
Pre-operation callout	The transaction processing resumes.	The transaction is aborted.	The transaction is in a waiting for a response.
Post-operation callout	The transaction completes with success state and may be removed from the store.	The transaction completes with failure state and may be removed from the store.	If “wait for post-operation callout” configuration option is enabled, then transaction remains parked. Otherwise, the transaction completes and may be removed from the store

Asynchronous transaction processing must be enabled if any callout may return a pending result. Otherwise, the transaction will always fail.

Callouts must implement the WorkflowCallout interface. Service Provider wraps relevant information about the transaction into a WorkflowAction object. Callouts return an ActionResult object with success, failure or pending enumerated values.

Callouts invoke the resumeWorkflowCallback method in order to resume a transaction that have been parked after returning a pending result. The com.sun.idm.idmx.txn.CalloutManager implements this interface.

Sample code that resumes a transaction:

WorkflowCallback callback = CalloutManager.getInstance();
   callback.resume(transactionId, ActionResult.SUCCESS);

The above mentioned interfaces are in the com.sun.idm.idmx.api package. Javadocs are provided in the Service Provider reference kit. The interfaces are still evolving, and future changes are possible.

Delegated Administration

By default, Service Provider implements the organization-based authorization model. In order to grant more fine grain capabilities and scope of control on Service Provider users, the admin role-based authorization model can be enabled using Service Prover user Admin Roles.

For more information about enabling admin Role-based delegated administration, see the Business Administrator's Guide.

A User Admin Role may be configured to evaluate several rules to determine the scope of control, capabilities, and dynamic assignment to a user:

• Scope of Control rules

  • User Search Context Rule

  • User Search Filter Rule

  • After Search Filter Rule

  Capabilities rule

  • Capabilities Per User Rule

  Assign to Users rules

  • Assign To User Rule

  • Assign To Service Provider User Rule

    Sample rules are located in the $WSHOME\sample\rules\adminRoleRules.xml file.

User Search Context Rule

A User Search Context rule is evaluated when searching for Service Provider users. It returns a valid LDAP distinguished name (DN). This DN serves as the base context for searching users. The authType for the rule must be set to SPEUsersSearchContextRule .

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsUser — The User view of the user the rule will run as. This is a null argument if runAsIDMXUser is specified.

runAsIDMXUser— The IDMXUser view of the user the rule will run as. This is a null argument if runAsUser is specified.

User Search Filter Rule

The User Search Filter rule is evaluated when searching for Service Provider users. It returns an LDAP-compliant filter string that will be logically ANDed with the user’s search filter when listing Service Provider users. The authType for the rule must be set to SPEUsersSearchFilterRule.

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsUser — The User view of the user the rule will run as. This is a null argument if runAsIDMXUser is specified.

runAsIDMXUser — The IDMXUser view of the user the rule will run as. This is a null argument if runAsUser is specified.

After Search Filter Rule

The After User Search Filter rule is evaluated when searching for Service Provider users. It runs after the initial search is performed against the Service Provider user directory. It returns a list of objectIds the requesting user is allowed to list and view.

This type of rule can be used to determine whether a user should be in the requesting user’s scope of control. To accomplish this, the rule can reference non-LDAP user attributes, such as LDAP group membership. The rule can also be used when the filter decision needs to be made using a repository other than the Service Provider user directory, such as an Oracle database or RACF.

The authType of this rule must be SPEUsersAfterSearchFilterRule.

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsUser — The User view of the user the rule will run as. This is a null argument if runAsIDMXUser is specified.

runAsIDMXUser — The IDMXUser view of the user the rule will run as. This is a null argument if runAsUser is specified.

objectType — Specifies the type of object, such as IDMXUser, that the rule filters.

objectIds — Specifies a list of objects the rule filters.

conditions — Specifies a list of AttributeConditions.

Capabilities Per User Rule

In the context of a Service Provider user Admin Role, capabilities specify which capabilities and rights the requesting user has on the Service Provider user for which access is being requested. The Capabilities Per User rule is evaluated when a request is made to view, create, modify, or delete an Service Provider user. It must be specified as a rule with authType CapabilitiesOnSPEUserRule.

The list of capabilities returned from the rule can include both existing Waveset capability names (such as “Service Provider Create User”) and Waveset right names (such as “Modify” and “Execute”).

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsUser — The User view of the user the rule will run as. This is a null argument if runAsIDMXUser is specified.

runAsIDMXUser — The IDMXUser view of the user the rule will run as. This is a null argument if runAsUser is specified.

object — Specifies the name of an object, if an object exists. Otherwise, null.

objectType — Specifies the type of object, such as IDMXUser, that the rule filters.

object.identity — Specifies the DN of the Service Provider user on which the request is being made.

object.attributes — Defines a map of attribute name/value pairs of the Service Provider user on which the request is being made. Sample name/value pairs include sn=Smith and cn=gsmith .

Assign To User Rule

Service Provider user Admin Roles can be dynamically assigned to Waveset users by specifying an Assign to User rule. This rule is evaluated at login time to determine whether to assign the authenticating Waveset user the AdminRole. The authType of this rule must be UserIsAssignedAdminRoleRule .

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsUser — Retrieves the User view of requesting user.

The output is a string or boolean true if the authenticating user should be assigned this AdminRole. Otherwise, false or null should be returned.

Assign To Service Provider User Rule

Service Provider User AdminRoles can be dynamically assigned to Service Provider users by specifying an Assign to Service Provider User rule. This rule is evaluated at login time to determine whether to assign the AdminRole to the authenticating Service Provider user. The authType of the rule must be SPEUserIsAssignedAdminRoleRule.

The rule is passed the following arguments:

context — Specifies current user’s identity context (session).

runAsIDMXUser — Retrieves the IDMXUser view of requesting user.

The output is a string or boolean true if the authenticating user should be assigned this AdminRole. Otherwise, false or null should be returned.