Managing Users and User Groups

The UserService interface provides functionality to manage users and their deputies, user groups and realms.

Managing Users

Creating Users

Creating a new user with specific details

Use the following method to create a user:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
User createUser(String realm, String account, String firstName, String lastName,
   String description, String password, String eMail, Date validFrom, Date validTo)
      throws UserExistsException, IllegalOperationException, InvalidPasswordException;

Hereby, the parameters determine the realm, account, first name, last name, description, password, email and validation date of the user.

Creating a new user with default realm Id

To create a new user with default realm Id, use the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
User createUser(String account, String firstName, String lastName, String description,
   String password, String eMail, Date validFrom, Date validTo)
      throws UserExistsException, IllegalOperationException, InvalidPasswordException;

Modifying Users

Modifying the current user

To modify the current user, use method modifyLoginUser:

User modifyLoginUser(String oldPassword, String firstName, String lastName,
    String newPassword, String eMail) throws ConcurrencyException,
      IllegalOperationException, InvalidPasswordException;

Parameter newPassword is the new password that will replace the old password, which has to be passed correctly via parameter oldPassword. Additionally you have to provide the first name, last name and email of the user.

Modifying a specific user

To modify a specific user use modifyUser:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
User modifyUser(User user) throws ConcurrencyException, ObjectNotFoundException,
   IllegalOperationException, InvalidPasswordException, AccessForbiddenException;

Parameter user determines the user to modify.

Note
If the modifyUser API is invoked in mixed mode (external and internal Authentication) to change the password and user information of an existing user, no Exception is thrown. The user information remains unchanged even though a successful response is provided.

Modifying a specific user and generating a password

With the following method you can modify a specific user and optionally generate a password:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
User modifyUser(User user, boolean generatePassword) throws ConcurrencyException, ObjectNotFoundException,
   IllegalOperationException, InvalidPasswordException, AccessForbiddenException;   

Parameter determines if a password should be generated. The password will be send per email to the user.

Resetting the password of a user

To reset the password of a specific user, use method resetPassword:

@ExecutionPermission(
   id = ExecutionPermission.Id.resetUserPassword, 
      defaults = { ExecutionPermission.Default.ALL })
   void resetPassword(String account, Map properties, String token) throws ConcurrencyException,
      ObjectNotFoundException, IllegalOperationException;

This method resets the password of the specified user by a generated password according to the configured password rules. On synchronization with external repository the specified user will be created in the audit trail if it is not already present there but exists in an external repository. If the user exists in the audit trail it will be updated on synchronization in case of any changes.

Parameter account determines the user account to be modified. A map providing further login properties is specified by properties. Parameter token determines the token generated by method generatePasswordResetToken(String).

Generating a password reset token

Use method generatePasswordResetToken to create a token for a user account, which is required for the resetPassword method described above.

@ExecutionPermission(
   id = ExecutionPermission.Id.resetUserPassword, 
      defaults = { ExecutionPermission.Default.ALL })
   void generatePasswordResetToken(String account);

Retrieving specific Users

Retrieving a user associated with a given account

You can retrieve a user associated with a given account via the following method:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   User getUser(String account) throws ObjectNotFoundException, IllegalOperationException;

On synchronization with an external repository the specified user will be created in the audit trail if it is not already present there but exists in an external repository. If the user exists in the audit trail it will be updated on synchronization in case of any changes.

Retrieving a user associated with a given account in a specific realm

You can retrieve a user associated with a given account in a specific realm via the following method:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   User getUser(String realm, String account) throws ObjectNotFoundException;

On synchronization with an external repository the specified user will be created in the audit trail if it is not already present there but exists in an external repository. If the user exists in the audit trail it will be updated on synchronization in case of any changes.

Retrieving a user with specified OID

To retrieve a user with a specific OID, use:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   User getUser(long userOID) throws ObjectNotFoundException;

On synchronization the user with the specified OID will be updated if this user exists in the audit trail and there are any changes. If this user does not exist in the audit trail but is present in an external repository it will not be created in audit trail on synchronization with external repository.

Invalidating Users

Invalidating a user with a specific account

Use the following method to invalidate a user with a specified account:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   User invalidateUser(String account) throws ObjectNotFoundException,
      IllegalOperationException;

Invalidating a user with a specified account and realm

To invalidate a user with a specific account in a specific realm, use:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   User invalidateUser(String realm, String account) throws ObjectNotFoundException,
      IllegalOperationException;

Retrieving Information on Users

Managing User Groups

Creating User Groups

To create a new user group, use the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   UserGroup createUserGroup(String id, String name, String description, Date validFrom,
      Date validTo) throws UserGroupExistsException, IllegalOperationException,
         InvalidPasswordException, InvalidArgumentException;

Specify the parameters for Id, name, description and validation date of the new user group.

Modifying User Groups

To modify a user group, use the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   UserGroup modifyUserGroup(UserGroup userGroup) throws ConcurrencyException,
      ObjectNotFoundException, IllegalOperationException;

Retrieving User Groups

Retrieving a user group with specific Id

To retrieve a user group with a specified Id, use the following method:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   UserGroup getUserGroup(String id) throws ObjectNotFoundException;

On synchronization with the external repository the specified user group will be created in the audit trail if it is not already present there but exists in the external repository. If the user group exists in the audit trail it will be updated on synchronization in case of any changes.

Retrieving a user group with specific OID

Use the following method to retrieve a user group with a specific OID:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   UserGroup getUserGroup(long oid) throws ObjectNotFoundException;

On synchronization the user group with the specified OID will be updated if this user group exists in the audit trail and there are any changes. If this user group does not exist in the audit trail but is present in the external repository it will not be created in the audit trail on synchronization with the external repository.

Invalidating User Groups

Invalidating a user group associated with a specific Id

You can invalidate a user group associated with a specific Id via the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   UserGroup invalidateUserGroup(String id) throws ConcurrencyException,
      ObjectNotFoundException, IllegalOperationException;

Invalidating a user group with a specific OID

To invalidate a user group with a specific OID, use:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   UserGroup invalidateUserGroup(long oid) throws ConcurrencyException,
      ObjectNotFoundException, IllegalOperationException;

Managing Realms

Creating User Realms

To create a new realm, use the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   UserRealm createUserRealm(String id, String name, String description)
      throws UserRealmExistsException, IllegalOperationException;

The parameters determine the Id, name and short description of the realm.

Dropping User Realms

To drop a user realm associated with a given Id, use the following method:

@ExecutionPermission(id=ExecutionPermission.Id.modifyUserData)
   void dropUserRealm(String id) throws ConcurrencyException, ObjectNotFoundException,
      IllegalOperationException;

Retrieving User Realms

You can retrieve all existing user realms by using the following method:

@ExecutionPermission(
   id=ExecutionPermission.Id.readUserData,
      defaults={ExecutionPermission.Default.ALL})
   List getUserRealms() throws ConcurrencyException, IllegalOperationException;

Managing Deputies

Adding Deputies

Use the following method to add a deputy for a given user:

Deputy addDeputy(UserInfo user, UserInfo deputyUser, DeputyOptions options) throws InvalidArgumentException;

Parameter user determines the user to which a deputy user should be added. Parameter deputyUser specified the deputy user. Both parameters are of type UserInfo. You can also add options associated with the operation via the parameter options of type DeputyOptions. This parameter can be null, in which case the default options are used.

The deputy user inherits for the defined time frame all grants from the given user. Note that the deputy user has to re-login before the inherited grants become active.

If argument for option toDate lies in the past, an InvalidArgumentException is thrown.

Modifying Deputies

To modify an existing deputy user for a given user, use the following method:

Deputy modifyDeputy(UserInfo user, UserInfo deputyUser, DeputyOptions options) throws ObjectNotFoundException, InvalidArgumentException;

This deputy user inherits for the defined time frame all grants from the given user. Note that the deputy user has to re-login before the changes become active.

If argument for option toDate lies in the past, an InvalidArgumentException is thrown.

Removing Deputies

Use the following method to remove an existing deputy user for a given user:

void removeDeputy(UserInfo user, UserInfo deputyUser) throws ObjectNotFoundException;

All inherited grants from the user are revoked from the deputy user. Note that the deputy user has to re-login to apply the changes.

Retrieving List of Deputies

To retrieve a list of all deputy users for a given user, use the following method:

List<Deputy> getDeputies(UserInfo user);

Retrieving List of Users being Deputy for

To retrieve a list of all users for which the given user is a deputy user, use:

List<Deputy> getUsersBeingDeputyFor(UserInfo deputyUser);