com.ibm.itim.apps.provisioning
Class AccountManager

java.lang.Object
  |
  +--com.ibm.itim.apps.provisioning.AccountManager

public class AccountManager

extends java.lang.Object

Provides aggregate account management capabilities. These capabilities include the creation of accounts, the validation of accounts, and the resolution of what services are available for an individual within the provisioning platform. Before creating an account, there should be (1) a person (account owner) who will own the account, (2) a service that will host this account, and (3) a provisioning policy for the service entitiled to the account owner. Account creation and modification are tied to the system's provisioning policies in a number of ways. For example, an account is "compliant" if it conforms with a provisioning policy. If the account does not conform with a provisioning policy, then it is a "non-compliant account". If there is no provisioning policy defined for the account, then it is marked "disallowed". Depending on the compliance status of the account and the policy enforcement of an account's host service, some account operations are not allowed. For example, if the account being created is "non-compliant" and the enforcement setting for the host service is set to "Suspend" or "Correct", then the account can not be created. In such case, ApplicationException will be thrown by the createAccount method.

See Also:

AccountMO

Constructor Summary

AccountManager(PlatformContext platform, javax.security.auth.Subject subject)
Constructs the manager with a platform context and a subject.

Method Summary

void	adopt(DistinguishedName ownerDN, java.util.Collection accounts) Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.
Compliance	checkAccountCompliance(PersonMO owner, ServiceMO service, AttributeValues params) Checks the account compliance on the given service with the given parameters for the given owner.
Request	createAccount(PersonMO owner, ServiceMO service, Account subject, java.util.Date scheduledTime) Creates an account in the provisioning platform with the specified attributes for the given person.
AttributeValues	getAccountParameters(PersonMO owner, ServiceMO service) Returns the auto-generated parameters used to define the potential owner's account on the given service.
java.util.Collection	getAccounts(PersonMO person, java.util.Locale locale) Returns the account(s) for the given person.
java.util.Collection	getAccounts(ServiceMO service, java.lang.String uid) Returns the account(s) with the uid hosted on the given service.
java.util.Collection	getAccounts(ServiceMO service, java.lang.String attributeName, java.lang.Object attributeValue) Returns the account(s) matching the given attribute hosted on the given service.
void	getAccounts(ServiceMO service, java.lang.String attributeName, java.lang.Object attributeValue, SearchResultsMO results) Returns the account(s) matching the given attribute hosted on the given service.
java.util.Collection	getAuthorizedServices(PersonMO subject, java.util.Locale locale) Returns the services the given person is authorized to have access to.
void	getNonCompliantAccounts(SearchResultsMO results) Returns all accounts that are currently tracked as non-compliant by the provisioning system.
void	getNonCompliantAccounts(ServiceMO service, SearchResultsMO results) Returns all accounts on the given service that are currently tracked as non-compliant by the provisioning system.
boolean	isAccountCompliant(AccountMO subject, java.util.Collection errors) Deprecated. Please use checkAccountCompliance method.
boolean	isAccountCompliant(PersonMO owner, ServiceMO service, AttributeValues params, java.util.Collection errors) Deprecated. Please use checkAccountCompliance method.
void	orphan(DistinguishedName userDN, java.util.Collection accounts) Orphans multiple accounts, or changes the account owner to unknown.
Request	remove(java.util.Collection accounts, java.util.Date scheduledTime) Removes multiple accounts from the provisioning platform.
Request	restore(java.util.Collection accounts, java.util.Date scheduledTime) Restores multiple accounts.
Request	restore(java.util.Collection accounts, java.lang.String password, java.util.Date scheduledTime) Restores multiple accounts with the password specified.
Request	suspend(java.util.Collection accounts, java.util.Date scheduledTime) Suspends multiple accounts.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AccountManager

public AccountManager(PlatformContext platform,
                      javax.security.auth.Subject subject)

Constructs the manager with a platform context and a subject.

Parameters:

platform - PlatformContext holding platform connection information.

subject - Subject representing the authenticated caller.

Method Detail

createAccount

public Request createAccount(PersonMO owner,
                             ServiceMO service,
                             Account subject,
                             java.util.Date scheduledTime)
                      throws java.rmi.RemoteException,
                             AuthorizationException,
                             SchemaViolationException,
                             ApplicationException

Creates an account in the provisioning platform with the specified attributes for the given person.

Parameters:

owner - PersonMO who will own the account.

service - ServiceMO the account will be provisioned on.

subject - Account value object defining the attributes the account will have.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to create an account for the given person or the client is unauthorized to write any of account attributes.

SchemaViolationException - Thrown if any of the attributes in the value object violates the managed object's schema. This may be caused by an invalid attribute or if a required attribute is missing entirely.

ApplicationException - Thrown if unable to submit the request. This may possibly be caused by 1. If the owner is removed by another client previous to this call. 2. If the password is not valid. (The actual exception will be the instance of InvalidPasswordException.) 3. If the account being created is non-compliant (or unauthorized) and the enforcement setting of the hosting service is set to "Suspend" or "Correct".

getAuthorizedServices

public java.util.Collection getAuthorizedServices(PersonMO subject,
                                                  java.util.Locale locale)
                                           throws java.rmi.RemoteException,
                                                  AuthorizationException,
                                                  ApplicationException

Returns the services the given person is authorized to have access to.

Parameters:

subject - PersonMO representing the person in question.

locale - optional Locale used to sort the results by Service name. If null, Locale.getDefault() (server JVM) is used.

Returns:

Collection of ServiceMO's representing the services the subject has access to. The empty collection will be returned if there is no service that is authorized for a subject person.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person.

ApplicationException - Thrown if unable to obtain the authorized services. This may possibly be caused by the subject being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to obtain the authorized services.

getAccountParameters

public AttributeValues getAccountParameters(PersonMO owner,
                                            ServiceMO service)
                                     throws java.rmi.RemoteException,
                                            AuthorizationException,
                                            ApplicationException

Returns the auto-generated parameters used to define the potential owner's account on the given service. Note, the client may not be authorized to view all of the parameters. These parameters will be omitted from the returned list without the generation of an AuthorizationException.

Parameters:

owner - PersonMO representing the person in question.

service - ServiceMO representing the service in question.

Returns:

AttributeValues holding the generated account parameters.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person, accounts of this type, and/or service.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the owner or service being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to generate the parameters or there is no policy defined for the owner and service.

getNonCompliantAccounts

public void getNonCompliantAccounts(SearchResultsMO results)
                             throws java.rmi.RemoteException,
                                    ApplicationException

Returns all accounts that are currently tracked as non-compliant by the provisioning system. The non-compliance may be due to unathorized access to a service completely, or just a constraint violation with the parameters of an account. Note, the client may not be authorized to view all of the accounts that are non-compliant. Those unauthorized accounts will be filtered out of the returned list and no AuthorizationException will be thrown.

Parameters:

results - SearchResultsMO to hold the results of the search. The SearchResultsMO is used support the paging and sorting for the presentation layer. The object will be filled with Account value objects that represent non-compliant accounts. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve the accounts. This may be also caused by a fault in data services area.

See Also:

SearchResultsMO

getNonCompliantAccounts

public void getNonCompliantAccounts(ServiceMO service,
                                    SearchResultsMO results)
                             throws java.rmi.RemoteException,
                                    ApplicationException

Returns all accounts on the given service that are currently tracked as non-compliant by the provisioning system. The non-compliance may be due to unathorized access to a service completely, or just a constraint violation with the parameters of an account. Note, the client may not be authorized to view all of the accounts that are non-compliant. Those unauthorized accounts will be filtered out of the returned list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO constraining the search.

results - SearchResultsMO to hold the results of the search. The SearchResultsMO is used support the paging and sorting for the presentation layer. The object will be filled with Account value objects that represent non-compliant accounts. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve the accounts.

See Also:

SearchResultsMO

isAccountCompliant

public boolean isAccountCompliant(AccountMO subject,
                                  java.util.Collection errors)
                           throws java.rmi.RemoteException,
                                  AuthorizationException,
                                  ApplicationException

Deprecated. Please use checkAccountCompliance method.

Returns whether the given account is compliant with all policies. Not only is a boolean result returned, but a list of errors (if any) are also available on request.

Parameters:

subject - AccountMO representing the account in question.

errors - If non-null, will be filled with detected errors. The errors are represented as Strings.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject account.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the account being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to evaluate compliance.

See Also:

checkAccountCompliance(PersonMO, ServiceMO, AttributeValues)

isAccountCompliant

public boolean isAccountCompliant(PersonMO owner,
                                  ServiceMO service,
                                  AttributeValues params,
                                  java.util.Collection errors)
                           throws java.rmi.RemoteException,
                                  AuthorizationException,
                                  ApplicationException

Deprecated. Please use checkAccountCompliance method.

Returns whether the an (potential) account on the given service with the given parameters for the given owner is compliant with all policies. Not only is a boolean result returned, but a list of errors (if any) are also available on request.

Parameters:

owner - PersonMO representing the person in question.

service - ServiceMO representing the service in question.

params - AttributeValues holding the parameters of the (potential) account.

errors - If non-null, will be filled with detected errors. The errors are represented as Strings.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person and/or service.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the owner and/or service being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to evaluate compliance.

See Also:

checkAccountCompliance(PersonMO, ServiceMO, AttributeValues)

checkAccountCompliance

public Compliance checkAccountCompliance(PersonMO owner,
                                         ServiceMO service,
                                         AttributeValues params)
                                  throws java.rmi.RemoteException,
                                         AuthorizationException,
                                         ApplicationException

Checks the account compliance on the given service with the given parameters for the given owner. The account is compliant if it conforms to the provisioning policy. This method returns the Compliance object and it has the information about the compliance status, the required AttributeChanges if the account is not compliant, and the attribute properties for the non-compliant attributes.

Parameters:

owner - PersonMO representing the person in question.

service - ServiceMO representing the service in question.

params - AttributeValues holding the parameters of the (potential) account.

Returns:

Compliance object that have the compliance status and the required AttributeChanges if the account is not compliant.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person and/or service.

ApplicationException - Thrown if unable to check the account compliance. This may possibly be caused by (1) the owner and/or service being removed by another client previous to this call, or (2)an error in processing policies in order to evaluate compliance.

Since:

ITIM 4.6

See Also:

Compliance

getAccounts

public java.util.Collection getAccounts(PersonMO person,
                                        java.util.Locale locale)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) for the given person. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

person - PersonMO representing the person to scope the search.

locale - optional Locale used to do a locale-sensitive sort of the results by user id. If null, Locale.getDefault() is used (server JVM).

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

getAccounts

public java.util.Collection getAccounts(ServiceMO service,
                                        java.lang.String uid)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) with the uid hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

uid - User id of the account to retrieve.

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

getAccounts

public java.util.Collection getAccounts(ServiceMO service,
                                        java.lang.String attributeName,
                                        java.lang.Object attributeValue)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) matching the given attribute hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

attributeName - Name of attribute to match with.

attributeValue - Value of the attribute to match with. A * can be used as the first and/or last character of a String value if a "contains" expression is wished.

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

getAccounts

public void getAccounts(ServiceMO service,
                        java.lang.String attributeName,
                        java.lang.Object attributeValue,
                        SearchResultsMO results)
                 throws java.rmi.RemoteException,
                        ApplicationException

Returns the account(s) matching the given attribute hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

attributeName - Name of attribute to match with.

attributeValue - Value of the attribute to match with. A * can be used as the first and/or last character of a String value if a "contains" expression is wished.

results - SearchResultsMO to hold the results of the search. The object will be filled with Account value objects that match the given criteria. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

adopt

public void adopt(DistinguishedName ownerDN,
                  java.util.Collection accounts)
           throws java.rmi.RemoteException,
                  AuthorizationException,
                  ApplicationException

Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.

Parameters:

ownerDN - DistinguishedName of the new account owner.

accounts - Collection of Account DirectoryObject to assign an owner to.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to modify any of the account or owner attribute of the account.

ApplicationException - Thrown if unable to adopt any of the accounts. This may possibly be caused by the account or owner being removed by another client previous to this call. Also thrown if the account is disallowed and the hosting service's enforcement action is set to "Correct".

orphan

public void orphan(DistinguishedName userDN,
                   java.util.Collection accounts)
            throws java.rmi.RemoteException,
                   AuthorizationException,
                   ApplicationException

Orphans multiple accounts, or changes the account owner to unknown.

Parameters:

userDN - DistinguishedName identifies an authenticated SystemUser.

accounts - Collection of Account DirectoryObjects to orphan.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to orphan any of the accounts.

ApplicationException - Thrown if unable to orphan the accounts. This may possibly be caused by (1) the account being removed by another client previous to this call, (2) the one of account is an ITIM account.

suspend

public Request suspend(java.util.Collection accounts,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Suspends multiple accounts. After the account is suspended, the account becomes inactive account.

Parameters:

accounts - Collection of Account DirectoryObjects to suspend.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to suspend any of the accounts.

ApplicationException - Thrown if unable to submit the request.

restore

public Request restore(java.util.Collection accounts,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Restores multiple accounts. If the account is disallowed or non-compliant and the enforcement action of hosting service is set to "Suspend" or "Correct", the account can not be restored. If one of accounts is in this category, then the ApplicationException will be thrown.

Parameters:

accounts - Collection of Account DirectoryObjects to restore.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to restore any of the accounts.

ApplicationException - Thrown if unable to submit the request. Also thrown if one of accounts is disallowed or non-compliant and the enforcement action of hosting service is set to "Suspend" or "Correct".

restore

public Request restore(java.util.Collection accounts,
                       java.lang.String password,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Restores multiple accounts with the password specified.

Parameters:

accounts - Collection of Account objects to restore.

password - Password to be used to restore the accounts.

The password will be used while restoring only accounts which satisfy all of the following conditions -
• The account supports a password change. This can be determined by checking the service the account is hosted on, for password requirements. Refer function 'isPasswordRequired' of ServiceMO for details.
• If a global flag in ITIM of suppressing the password specification during restore is set to true, but the service profile hosting the account requires the password specification during restore, or if the global flag set to false.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if there is a communication failure.

AuthorizationException - Thrown if client is unauthorized to restore any of the accounts.

ApplicationException - Thrown if business rules are violated, while performing requested operation, for example when any one of the accounts in the collection is an orphan account. This exception may be thrown if any account in the collection is a non-compliant or disallowed account governed by a service with policy enforcement set to "Suspend" or "Correct".

remove

public Request remove(java.util.Collection accounts,
                      java.util.Date scheduledTime)
               throws java.rmi.RemoteException,
                      ApplicationException,
                      AuthorizationException

Removes multiple accounts from the provisioning platform. If there is an automatic provisioning policy defined for a person and a service, then a person should have at least one account on that service. If all these accounts are requested to be deleted, then the ApplicationException will be thrown.

Parameters:

accounts - Collection of Account DirectoryObjects to remove.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to remove any of the accounts.

ApplicationException - Thrown if unable to submit the request. This may caused by (1) if the account was already removed by another client prevous to this call, or (2) if the accounts being removed are required by the automatic provisioning policy.