WebMO Help - External Authentication (Enterprise)

Authentication of WebMO Users

Each WebMO instance maintains its own database of WebMO users (which are distinct from system users) who may access the WebMO instance and run computational chemistry jobs. By default, WebMO authenticates users when they login against a locally stored hash of a password. The initial password is set by a WebMO administrator, but can be changed by the user.

WebMO Enterprise provides a mechanism for authenticating WebMO users against an external source rather than the internal hashed password. A common external authentication mechanism is LDAP (Lightweight Directory Access Protocol), which allows authentication of WebMO accounts against a directory of usernames and passwords maintained by an LDAP server. LDAP service is typically implemented at an enterprise level by an organization's Information Technology department. Alternatively, many institutions now use Shibboleth Single Sign-On or Active Directory, with which WebMO can use for authentication. Another very useful authentication mechanism is PAM, which allows authentication of WebMO accounts against the existence of a system account on the same computer. PAM delegates all authentication to the PAM (pluggable authentication module) of the underlying operating system and thereby creates the mapping between "webmo" users and "system" users necessary for running jobs under a system user's UID and storing jobs in a system user's home directory. Other forms of external authentication recognized by WebMO include and POP3, NIS, and /etc/password.

Enabling external authentication does not disable internal authentication. Thus, it is possible to have both internally and externally authenticated accounts at the same time. However, only one external authentication mechanism is permitted at a time.

After configuring external authentication, external authentication is enabled in the System Manager. Once enabled, individual accounts can be set to use either internal or external authentication through the User Manager. See below for details.

External authentication is advantageous for users, as they can use their existing username and password to access WebMO. Also, any changes they make to their password are automatically recognized by WebMO. External authentication is useful for administrators, as it relieves them of providing forgotten usernames and resetting lost passwords.

Note that WebMO usernames are translated and maintained in lowercase in order to be case-insensitive. Thus external authentication mechanisms must be able to accept usernames in lower-case names.

External Authentication can be configured to allow users to create a WebMO account, thereby relieving the WebMO administrator of having to create WebMO accounts for externally authenticable users.

External authentication is highly recommended for large numbers users (e.g., students at a college or university) or when WebMO usage is to be integrated with other services (e.g., providing system users with WebMO access).

Configuring External Authentication

  1. If using Shibboleth single sign-on, complete the following and then go to step 7. No CPAN modules are installed, but additional setup is required:
    A. Install and configure Shibboleth on the server (details will vary from campus-to-campus and are not specific to WebMO).
    B. Enable Shibboleth via the Apache web server. Add the following lines to httpd.conf:
    <Location /~webmo/cgi-bin/webmo/login.cgi>
      <If "%{QUERY_STRING} == ''">
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        require shib-session
      </If>
    </Location>
    C. Install perl-Authen-Simple using yum (or apt-get for Debian):
    # yum install perl-Authen-Simple
    When accessing the normal WebMO login url (.../login.cgi), users will be re-directed to the campus sign-on page. Note that WebMO administrators and local WebMO users must use a url like .../webmo/login.cgi?local_user to bypass single-sign on.
    D. Configure username mapping:
    Note that WebMO in conjunction with Shibboleth uses the REMOTE_USER environmental variable to determine the proper username for the authenticated user. This variable is populated according to the <ApplicationDefaults> set in shibboleth2.xml via a list of attributes. You may wish to prepend an additional attribute to this list to modfy this mapping (e.g. to use 'jsmith' vs. 'jsmith@university.edu' as the username)
  2. For non-Shibboleth authentication, install any relevant software packages on the system that are needed to support perl, CPAN, and compilation of c source code needed for the perl authentication modules. For example, on a CentOS 7 system:
    # yum install perl perl-CPAN perl-Parse-CPAN-Meta perl-CPAN-Meta-Requirements
    # yum install gcc pam-devel
  3. Optionally, update the CPAN to the current version. i.e., more recent than the version provided in the Linux distribution.
    # perl -MCPAN -e "install CPAN"
  4. Install the relevant perl authentication library, depending on the authentication mechanism to be used:
            Authen::Simple::LDAP
            Authen::Simple::POP3
            Authen::Simple::NIS
            Authen::Simple::Passwd
            Authen::Simple::PAM
            Authen::Simple::ActiveDirectory
    For example,
    # perl -MCPAN -e "install Authen::Simple::LDAP"
    Follow prompts and make reasonable choices.
    Note: you might need to temporarily turn off your firewall to perform this installation
  5. If using PAM authentication, install the pam_authenticate.pl script.
    $ mkdir /home/webmo/bin
    $ cp -p {download_dir}/WebMO.install/scripts/pam_authenticate.pl /home/webmo/bin/
    $ chmod 775 /home/webmo/bin/pam_authenticate.pl
    Edit {cgiBase}/interfaces/authen.conf to reflect the location of pam_authenticate.pl.
  6. If necessary, edit {cgiBase}/interfaces/authen.conf to reflect location of LDAP or POP3 server.
  7. Edit /etc/sudoers as necessary.
    AUTHEN is needed for PAM authentication. SYSCMD and QCMD are needed for running jobs under UID's. The 'requiretty' option MUST NOT be present, otherwise the WebMO scripts will not be able to run sudo non-interactively.
    # visudo
    Remove or comment out the "requiretty" option.
    If using the SGE queuing system, add "SGE_ROOT" to the "env_keep" list.
    Add the lines:
    # WebMO user
    Cmnd_Alias SYSCMD = /bin/chown,/bin/chmod,/bin/mkdir
    Cmnd_Alias QCMD = /usr/local/bin/qsub,/usr/local/bin/qstat,/usr/local/bin/qdel,/usr/local/bin/qalter
    Cmnd_Alias AUTHEN = /home/webmo/bin/pam_authenticate.pl
    webmo ALL=(ALL) NOPASSWD: QCMD, SYSCMD, AUTHEN
    #Add any environmental variables you use that must be preserved
    Defaults env_keep += "SLURM_CONF"
    If using the SLURM queuing system, then QCMD must instead reference the analogous sbatch, squeue, scancel, and scontrol commands. The QCMD entries must match the commands that are entered into the Batch Queue Manager.
  8. Enable external authentication.
    Login as the WebMO administrator. Choose System Manager. Under Authentication, choose desired type of authentication. If using sudo, check "Enable sudo usage". Click Submit and Return to Admin.
  9. Optionally, choose one or more groups that new users may join.
    Choose Group Manager. Edit desired group. Check "Allow externally-authenticated new users to join this group". Set password for joining group, if desired. Click Submit and Return to Group Manager. Repeat as necessary for additional groups. Click Return to Admin.
  10. Set up a user for external authentication.
    Choose User Manager. Edit user {smith}. Check "Externally authenticate this user" and click Submit. Click Return to User Manager, Return to Admin, and Logout.
    Note: This process is only for pre-existing users who were created with an internal password and now wish to change to external authentication. New users that are created via external authentication will have this box checked automatically.
  11. Test external authentication.
    Login as user {smith} with the external password.
    If this is user {smith}'s first login to WebMO, they will be prompted to join a group and must provide the group password if it was set. Run a test job.
  12. Run apache over SSL.
    Since organizational or system passwords will be transmitted via the web, it is highly recommended that your webserver be run as a secure server. Consult web resources on how to configure your apache webserver to redirect or rewrite all http requests as https requests. Be sure that your firewall allows access to port 443 (https) in addition to port 80 (http). Also, the default certificate may cause warnings, in which case you can create a key, create a certificate, sign the certificate, edit httpd.conf to point to the new certificate, and restart your webserver.

Creating New Users via External Authentication

WebMO can be configured aso that non-WebMO users may externally authenticate and have an account automatically created for them. This feature allows WebMO accounts to be created without manual intervention by a WebMO administrator.

To enable externally authenticated WebMO account creation, login as the WebMO administrator. Choose Group Manager. Edit the desired group. On the Password tab, check the "Allow externally-authenticated new users to join this group" option. Optionally provide a group password. Click the Submit button.

The purpose of the Group password is to provide additional control over whether external-authentication permits the creation of a new WebMO account. If externally-authenticated users are allowed to join the group and no group password is set, then anyone who can externally authenticate themselves can create a WebMO account in the group. However, if a group password is set, then the person must both externally authenticate and provide the group password in order to be allowed to create a new webMO account.


External Authentication of New Users

Note: The Group Password is different from the admin-{group} password. The Group Password is used by potential new WebMO users to have an account created in a particular group. The admin-{group} password is used by the admin-{group} user to log into the WebMO as a group administrator and perform administration functions.

By providing the group password to only a limited number of people, then the ability to create new webMO accounts is limited to a subset of those who are contained in the external authentication database. The ability to provide separate Group Passwords to groups allows potential users to be directed into different WebMO groups depending on which group password they were given.


New User Log In and Group Selection

To limit the automatic creation of WebMO accounts to a subset of externally authenticable users (e.g., to only students in one course at a university), create a group, enable external authentication for the group, and set a group password. Supply the group password to the desired users. Only potential users with the knowledge of the group password will be allowed to self-authenticate.

Changing Internal vs. External Authentication

When creating a new user as an WebMO administrator, an internal password must always be provided. The WebMO administrator can then choose whether the user should be externally authenticated.

To change the authentication of a user, login as the WebMO administrator. Choose User Manager. Edit the desired user. On the Password tab, check or uncheck "Externally authenticate this user" and click Submit. Click Return to User Manager. Click Return to Admin and Logout.


Externally Authenticate a User

If a user was created by external authentication, then no internal password exists for the user and the user cannot login with internal authentication. In this case, a password must be created by a WebMO administrator with the User Manager in order for the user to login with internal authentication. From the User Manager, edit the desired user, provide a new password on the Password tab, uncheck "Externally authenticate this user", and click the Submit button.

If the WebMO administrator changes authentication from external authentication to "Built-in WebMO authentication", then external authentication is disabled for all accounts. Accounts created by external authentication will not be allowed to login because they have no internal password.

Important: WebMO access credentials are cached between web page accesses. So to test whether an internal or external password authentication is happening, one must fully exit and then restart the web browser, so as to clear the cached credential.