Matrix Science header
Public Types | Public Member Functions

ms_security Class Reference
[Mascot security and authentication module]

The main security class to be used by the administration application. More...

#include <ms_security.hpp>

Inheritance diagram for ms_security:
Inheritance graph
[legend]
Collaboration diagram for ms_security:
Collaboration graph
[legend]

List of all members.

Public Types

enum  USERID_SORTBY {
  USERID_SORTBY_ID = 1,
  USERID_SORTBY_LOGINNAME = 2,
  USERID_SORTBY_FULLNAME = 3
}
 

Sorting criterion to retrieve all users.

More...

Public Member Functions

 ms_security ()
 The constructor loads all the groups and users information from the ../config directory.
bool addNewGroup (const std::string sessionID, const int groupID, const std::string groupName)
 Add a new group to the current list of groups.
bool addNewUser (const std::string sessionID, const int userID, const std::string userName, const std::string password, const time_t passwordExpiry, const std::string fullName, const std::string emailAddress, const ms_user::usertype userType, const bool enabled)
 Add a new user to the current list of users.
void appendErrors (const ms_errors &src)
 Copies all errors from another instance and appends them at the end of own list.
void clearAllErrors ()
 Remove all errors from the current list of errors.
void copyFrom (const ms_errors *right)
 Use this member to make a copy of another instance.
bool createDefaults (const std::string sessionID="")
 Create default users, groups and sessions.
bool deleteGroup (const std::string sessionID, const std::string groupName)
 Delete a group from the system.
bool deleteUser (const std::string sessionID, const std::string userName)
 Delete a user from the system.
ms_user::customParams_t getAllCustomParamsForUser (const ms_user &user) const
 Return a 'map' of all the custom parameters for a user.
std::vector< int > getAllGroupIDs () const
 Return a list of all group IDs.
std::vector< int > getAllUserIDs (const USERID_SORTBY sortby=USERID_SORTBY_ID) const
 Return a list of all user IDs.
const ms_errsgetErrorHandler () const
 Retrive the error object using this function to get access to all errors and error parameters.
ms_group getGroup (const std::string groupName) const
 Return a group given the name .
ms_group getGroupFromID (const int groupID) const
 Return a group given the ID.
std::vector< std::string > getIntegraUsers () const
 Returns a list of Integra users.
int getLastError () const
 Return the error description of the last error that occurred.
std::string getLastErrorString () const
 Return the error description of the last error that occurred.
ms_security_options getMascotSecurityOptions () const
 Return the security options.
ms_security_tasks getPermittedTasksForUser (const std::string name) const
 Return a list of the tasks permitted for the user.
ms_security_tasks getTasks () const
 Return the complete list of possible tasks available.
ms_user getUser (const std::string userName) const
 Return a user given the name.
ms_user getUserFromID (const int userID) const
 Return a user given the ID.
bool isTaskExists (const int taskID) const
 Return true if a security task with the given ID exists.
bool isUserExists (const int userID) const
 Return true if a user with this ID exists.
bool isValid () const
 Call this function to determine if there have been any errors.
std::vector< int > sortUsers (std::vector< ms_user * > &vecUsers, const USERID_SORTBY sortby) const
 Sort a list of users and return a list of user IDs.
bool updateAllSessionFiles (bool deleteOnly=false)
 Update all the session files after making a change to parameters.
bool updateGroup (const std::string sessionID, const ms_group &group)
 Call this after updating any details for a group.
bool updatePassword (const std::string sessionID, const std::string userName, const std::string oldPassword, const std::string newPassword)
 Update the password for an existing user.
bool updateUser (const std::string sessionID, const ms_user user)
 Update an existing user int the system.

Detailed Description

The main security class to be used by the administration application.

Other applications should just need to use ms_session.

When an object of this class is created, it loads all the users, groups tasks and options into memory.


Member Enumeration Documentation

Sorting criterion to retrieve all users.

Enumerator:
USERID_SORTBY_ID 

Sort the list of users id by id.

USERID_SORTBY_LOGINNAME 

Sort the list of users id by login name (its displayed name)

USERID_SORTBY_FULLNAME 

Sort the list of users id by full name.


Constructor & Destructor Documentation

ms_security (  )

The constructor loads all the groups and users information from the ../config directory.

The administration program should use this constructor to load all users, groups and tasks. New users and groups should be added through this interface.


Member Function Documentation

bool addNewGroup ( const std::string  sessionID,
const int  groupID,
const std::string  groupName 
)

Add a new group to the current list of groups.

To add a new group, call this function first. If the function returns true, then get the group using getGroup(), add users and tasks to the group and then call updateGroup().

Parameters:
sessionIDThis is the session id for the administrator who is adding the user. A valid session ID with administrator rights is required, and all additions of users and groups are logged using the details in the session ID.
groupIDCan be set to -1 in which case the system provides a new unique ID. If a value is provided, and there is already a group with this ID, then the function will return false and the error ms_errs::ERR_MSP_SECURITY_DUPE_GROUP_ID.
groupNameIs the name of the new group to be added. This must not contain spaces or any of the following characters:

><\\/`;,+*" 

If there is already a group with this name, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_GROUP_NAME.

Returns:
True if the function succeeds. The function will fail if the session is invalid, or doesn't have administrator rights. The function will also fail if there is a group with a the same name or the same ID.
bool addNewUser ( const std::string  sessionID,
const int  userID,
const std::string  userName,
const std::string  password,
const time_t  passwordExpiry,
const std::string  fullName,
const std::string  emailAddress,
const ms_user::usertype  userType,
const bool  enabled 
)

Add a new user to the current list of users.

Use this function, rather than ms_user::ms_user to add a new user to the system.

Possible errors are:

Parameters:
sessionIDThis is the session id for the administrator who is adding the user. A valid session ID with administrator rights is required, and all additions of users and groups are logged using the details in the session ID.
userIDCan be set to -1 in which case the system provides a new unique ID. If a value is provided, and there is already a user with this ID, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_USER_ID.
userNameThe user name must not contain spaces or any of the following characters:

><\\/`;,+*" 

If there is already a user with this name, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_USER_NAME.

passwordThe password length must be greater than or equal to ms_security_options::getMinimumPasswordLength() unless the passwordExpiry parameter is set to 1, in which case the user will be prompted for a new password when they log in.
passwordExpiryis the time in seconds since Jan 1, 1970 when the password will expire. See ms_security_options::getDefaultPasswordExpiryTime() for details. A value of '0'is used to indicate that the password should never expire. A value of 'now' or 1 can be used to force the user to change their password next time they log in.
fullNameCan be any number of characters, but ideally should not be left blank.
emailAddressCan be any number of characters, but ideally should not be left blank. No error checking is performed in this function.
userTypemust be ascertained correctly by the calling application, since there is no error checking in this function. Normally, this function should only be called with one of

The type should never be ms_user::USER_SECURITY_DISABLED

enabledShould normally be set to true to allow the user to login.
Returns:
True if successful.
void appendErrors ( const ms_errors src ) [inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:
srcThe object to copy the errors across from. See Maintaining object references: two rules of thumb.
void clearAllErrors (  ) [inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:
isValid(), getLastError(), getLastErrorString(), getErrorHandler()
Examples:
common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
bool createDefaults ( const std::string  sessionID = "" )

Create default users, groups and sessions.

This function should be called by the installation program to create all the default users, default groups, default sessions etc. if they don't already exist.

This function creates:

Parameters:
sessionIDWill generally be the built in command line session that is automatically created for any programs not being run from the web server.
Returns:
True if the function succeeds. Possible errors are: ms_errs::ERR_MSP_SECURITY_INVALID_SESSION_ID, ms_errs::ERR_MSP_SECURITY_NOT_ADMIN_SESSION and all errors that can be set from calling addNewUser() and addNewGroup().
bool deleteGroup ( const std::string  sessionID,
const std::string  groupName 
)

Delete a group from the system.

Possible error values are:

Parameters:
sessionIDThis is the session id for the administrator who is deleting the group. A valid session ID with administrator rights is required, and all deletions of users and groups are logged using the details in the session ID.
groupNameNeeds to be a valid user name.
Returns:
Will return true if the function succeeds in deleting the group. Otherwise, it will return false and set just one of the above errors.
bool deleteUser ( const std::string  sessionID,
const std::string  userName 
)

Delete a user from the system.

Possible error values are:

Parameters:
sessionIDThis is the session id for the administrator who is deleting the user. A valid session ID with administrator rights is required, and all deletions of users and groups are logged using the details in the session ID.
userNameNeeds to be a valid user name.
Returns:
Will return true if the function succeeds in deleting the user Otherwise, it will return false and set just one of the above errors.
ms_user::customParams_t getAllCustomParamsForUser ( const ms_user user ) const

Return a 'map' of all the custom parameters for a user.

If an invalid user object is passed, then the returned object will be empty

Customer parameters for a user can originate from the user or group settings. Values at the user level overwrite values at the group level. See Using custom parameters

Parameters:
userNeeds to be a valid user object.
Returns:
a 'map' of custom parameters and values.
std::vector< int > getAllGroupIDs (  ) const

Return a list of all group IDs.

To find details of each group, call getGroupFromID().

Returns:
An array of user IDs. See Using STL classes in Perl, Java, Python and C#.
std::vector< int > getAllUserIDs ( const USERID_SORTBY  sortby = USERID_SORTBY_ID ) const

Return a list of all user IDs.

To find details of each user, call getUserFromID().

Parameters:
sortbyThe field on which to sort the users whose IDs are returned, by default they are sorted by id
Returns:
An array of user IDs. See Using STL classes in Perl, Java, Python and C#.
const ms_errs * getErrorHandler (  ) const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:
Constant pointer to the error handler
See also:
isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, and http_helper_getstring.cpp.
ms_group getGroup ( const std::string  groupName ) const

Return a group given the name .

If an invalid group name is passed, then for the returned object, ms_group::getID() will return -1.

Parameters:
groupNameNeeds to be a valid group name.
Returns:
an ms_group object.
ms_group getGroupFromID ( const int  groupID ) const

Return a group given the ID.

If an invalid group ID is passed, then for the returned object, ms_group::getUserID() will return -1.

Parameters:
groupIDNeeds to be a valid group ID.
Returns:
an ms_group object.
std::vector< std::string > getIntegraUsers (  ) const

Returns a list of Integra users.

Deprecated:
Mascot Integra is not supported in Mascot Parser 2.5 and later.

Will return an empty list if there is no local Mascot Integra system or the definitions in the option file are not correct. These users have not neccessarily been added to the list of Mascot users.

Returns:
An array of Integra user names. See Using STL classes in Perl, Java, Python and C#.
int getLastError (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:
isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Returns:
the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:
Most recent error, warning, information or debug message

See Error Handling.

See also:
isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.
ms_security_options getMascotSecurityOptions (  ) const

Return the security options.

If an ms_security object is available, it is faster to call this than creating a new matrix_science::ms_security_options object because there will be no need to load the options file from disk.

Note that this function returns a copy of the security options, so changing the options will have no effect on the ms_security object. To have the changes take effect, a new ms_security object will have to be created.

Returns:
The security options. If the configuration file is not present, defaults will be used.
ms_security_tasks getPermittedTasksForUser ( const std::string  name ) const

Return a list of the tasks permitted for the user.

If an invalid user name is passed, then for the returned object, ms_security_tasks::getNumberOfTasks() will return 0.

Parameters:
nameNeeds to be a valid user name.
Returns:
A ms_security_tasks object.
ms_security_tasks getTasks (  ) const

Return the complete list of possible tasks available.

The administration module will use this function to display a list of possible tasks to the end user.

Returns:
The complete list of tasks.
ms_user getUser ( const std::string  userName ) const

Return a user given the name.

If an invalid user name is passed, then for the returned object, ms_user::getID() will return -1.

Parameters:
userNameNeeds to be a valid user name.
Returns:
an ms_user object.
ms_user getUserFromID ( const int  userID ) const

Return a user given the ID.

If an invalid user ID is passed, then for the returned object, ms_user::getUserID() will return -1.

Parameters:
userIDNeeds to be a valid user ID.
Returns:
an ms_user object.
bool isTaskExists ( const int  taskID ) const

Return true if a security task with the given ID exists.

Parameters:
taskIDTask ID to check.
Returns:
true if a task with this ID exists; false otherwise.
bool isUserExists ( const int  userID ) const

Return true if a user with this ID exists.

Parameters:
userIDUser ID to check.
Returns:
true if a user with this ID exists; false otherwise.
bool isValid (  ) const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:
True is no fatal error occured
See also:
getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.
std::vector< int > sortUsers ( std::vector< ms_user * > &  vecUsers,
const USERID_SORTBY  sortby 
) const

Sort a list of users and return a list of user IDs.

Sorts a list of users by the given field

Parameters:
vecUsersA vector of users to sort
sortbyThe field on which to sort the users whose IDs are returned
Returns:
An array of user IDs sorted by id, login name or full name
bool updateAllSessionFiles ( bool  deleteOnly = false )

Update all the session files after making a change to parameters.

This function is called by addNewUser(), deleteUser(), updateUser(), addNewGroup(), deleteGroup() and updateGroup().

Parameters:
deleteOnlyis set to true when this function is called from ms-monitor.exe. This prevents session files from being created with the incorrect file permissions.
Returns:
always returns true
bool updateGroup ( const std::string  sessionID,
const ms_group group 
)

Call this after updating any details for a group.

Groups can be changed by adding/deleting users, changing the name or adding/deleting tasks. To make any of these changes, call getGroup() or getGroupFromID() to get the group and then make changes using the ms_group member functions. Finally, call this function to make the changes permanent. Do not change the groupID, or this function will fail.

Possible errors are:

Parameters:
sessionIDThis is the session id for the administrator who is updating the group. A valid session ID with administrator rights is required, and all updates of users and groups are logged using the details in the session ID.
groupThe group returned from getGroup() or getGroupFromID().
Returns:
True if the group already exists and has been successfully updated.
bool updatePassword ( const std::string  sessionID,
const std::string  userName,
const std::string  oldPassword,
const std::string  newPassword 
)

Update the password for an existing user.

If the old password is empty, or is supplied, then anyone can call this function. If the sessionID is for a valid session with Administrator privileges, then the old password is not required.

Possible errors are:

Parameters:
sessionIDIs the session ID for a session with Administrator permissions or a session for the named user.
userNameNeeds to be an existing user name.
oldPasswordThe old password must be correct.
newPasswordThe password will be updated with the new value.
Returns:
Will return true if the password has been updated successfully.
bool updateUser ( const std::string  sessionID,
const ms_user  user 
)

Update an existing user int the system.

Most properties of a user account can be changed -- for example the login name, or the full name or email address. The ID cannot be changed. The password must be changed using updatePassword(). To change which groups a user belongs to, see updateGroup().

To call this function, the session must either have ms_security_tasks::SECTASK_ADMINPAGES or ms_security_tasks::SECTASK_MODIFYOWNPROFILE rights. In the latter case, the user to be updated must be the same as the session user, and the only things that can be changed are the full name and the email address.

Possible errors are:

Parameters:
sessionIDIs the session ID for a session with Administrator permissions.
userNeeds to be an existing user. All details will be reset with the passed information, including the password.
Returns:
Will return false and set ms_errs::ERR_MSP_SECURITY_USERNAME_NOT_FOUND if the named user cannot be found.

The documentation for this class was generated from the following files:
Copyright © 2016 Matrix Science Ltd.  All Rights Reserved. Generated on Fri Jun 2 2017 01:44:54