Introduction

The design goals of the Mascot security module include the following:

Restrict access to results files and sequence databases based on group and user definitions.
Allow authorised users to change Mascot server configuration files in a secure and traceable manner using thin client web based GUI tools that are supplied with Mascot Server.
Prevent un-authorised changes of Mascot server configuration files.
Standard 'session' support (with time-outs) so users do not need to re-enter passwords.
Restrict access to Mascot server based utilities that allow deletion of searches and other job control functions.

Mascot security from a fat client application

A client application can perform most tasks using the login.pl script that is installed in the mascot/cgi directory. A copy is supplied with Mascot Parser and the available commands can be seen at the start of the file.

Calls to most applications on Mascot server require a sessionID parameter. To see if security is disabled, use the login.pl script:

    http://mascot_server/mascot/cgi/login.pl?action=issecuritydisabled&display=nothing

If this returns a valid sessionID, then the sessionID can (but doesn't need to be) passed to any of the applications that accepts a sessionID.

If this call returns an error (and hence doesn't return a sessionID), then try:

    http://mascot_server/mascot/cgi/login.pl?action=webauthentication&display=nothing

If this succeeds, then either the Mascot web server is set up to use IIS integrated authentication, or a user name and password have to be specified in the URL. You can use the returned sessionID as above. If the call returns an error (and hence doesn't return a sessionID), then try

    http://mascot_server/mascot/cgi/login.pl?action=guestlogin&display=nothing

If this succeeds, then an interface should be provided to allow the user to log into the system as a different user with more rights. By default, the guest account is disabled on Mascot servers.

If this also fails (or if you choose not to call it), then the user must be prompted for a user name and password. Pass the username and password to the login.pl script:

    http://mascot_server/mascot/cgi/login.pl?action=login&username=xxx&password=yyy&display=nothing

If this returns an error, you should display the errorstring= value to the end user and prompt once again for the user name and password. Possible errors are listed in the documentation for ms_session().

A special case of ERR_MSP_SECURITY_PASSWORDEXPIRED can be handled by asking for the old and new passwords, and then calling login.pl with the appropriate parameters. Alternatively, a poor solution is to suggest that the user logs into Mascot using a browser and updates their password there.

The sessionID should be passed to daemon.pl and nph-mascot.exe. See documentation for those applications for further details.

Using the ms_session class from a CGI application

For most CGI applications, the only requirement is to create an ms_session object, check that it is valid (isValid()), and then use the methods isPermitted(), isPermitted_long(), etc.

If isValid() returns false, then the error should be treated as described in the ms_session constructor.

Using custom parameters

ms_session, ms_user and ms_group objects can store and retrieve custom string parameters using the methods saveStringParam() and getStringParam(), and the corresponding methods for integers, doubles and booleans. In each case, the key/value pairs are saved in a <mss:custom_parameters> section of the relevant XML files; for example, ms_user custom parameters are saved in user.xml. Custom parameters for ms_user and ms_group were added in Mascot Parser 2.4.1.

Custom parameters are typically used with a temporary session object, which is independent of users and Mascot security and is created with the ms_session(const int, const std::string) constructor. However, it is also possible to use custom parameters with a user session, which is created when a user logs in to Mascot. The rest of this section deals with user sessions.

User sessions can contain three types of custom parameters: parameters saved in the session (ms_session), parameters saved in group.xml (ms_group) and parameters saved in user.xml (ms_user). ms_session custom parameters in user session files are lost when the session file is rewritten. A rewrite may occur, for example, after editing user settings in Mascot Configuration Editor. Both ms_user and ms_group custom parameters survive a rewrite.

Custom ms_user and ms_group parameters are copied to the relevant user session files when ms_security::updateUser or ms_security::updateGroup are called. It is of course possible for ms_user and ms_group objects to contain custom parameters with the same name. Only one value will be saved in the user session file, and parameters from ms_user override parameters from ms_group.

Advanced

The administration utility uses the ms_security class to add users (addNewUser()) and groups (addNewGroup()). Refer to the class documentation for further details.