Login Protocols and Single Sign-on (SSO)

Access to LiveWhale can be configured in different ways.

By default, LiveWhale will use its own built-in authentication scheme. Usernames and (encrypted) passwords are stored in the LiveWhale database, and the login functionality is database driven.

You can also configure LiveWhale to manage logins using:

Note: LiveWhale only supports one authentication method at a time. If you switch to an SSO or LDAP login, the built-in password system will be bypassed. You can switch back-and-forth for testing.

Steps to Configure Authentication

  1. Open the core LiveWhale config (/livewhale/core/config.php) using an FTP client or via the command line.
  2. Configure the type of login you wish to use with the LOGIN_MODE setting. Set it to “password”, “LDAP”, “SAML”, “google”, “CAS” or the name of your plugin (i.e., “my_plugin”).
  3. If you are not using the “SSO” or “SAML” mode, set the LOGIN_TIMEOUT and LOGIN_SECURE settings as desired. LOGIN_TIMEOUT determines the amount of time a person should remain logged in before their session expires. LOGIN_SECURE forces logins to persist over HTTPS only (recommended). These settings are not applicable in SSO or SAML mode.
  4. If you are using the “LDAP” mode, fill out the LDAP settings. See table below for setting descriptions. If you are using “google” mode, add the required API keys as indicated below.
  5. If you are using “SSO” mode, you may add a LOGOUT_URL setting to your master LiveWhale config to direct users to your custom logout page providing any additional instructions relevant to the SSO that you may have (i.e. quit your browser, etc.)

Enabling LOGIN_SECURE is a highly recommended security feature. When enabled, all LiveWhale logins will take place over SSL (HTTPS) connections, and will enforce that HTTPS is used throughout the duration of the session. In order to use this feature, your site must be fully accessible over SSL.

Failed logins will be recorded in the server log, including the username that was attempted. This can be reviewed to detect malicious login attempts, or to discover a user who may have forgotten their login credentials.

Default Configuration

1
$GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='password';

Password mode is the default configuration for LiveWhale. Encrypted passwords are stored in the livewhale_users table for each editor account.

If you use any other login protocol, those stored passwords are bypassed (but not deleted). This means if later you run into issues with your SSO, you can switch back to password mode and use those old passwords (or click “Forgot your password?” to set a new one).

LDAP Configuration

1
2
3
4
5
6
$GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='LDAP';
$GLOBALS['LIVEWHALE_CONFIG']['LDAP_HOST']='ldap.your-domain.edu';
$GLOBALS['LIVEWHALE_CONFIG']['LDAP_PORT']='636';
$GLOBALS['LIVEWHALE_CONFIG']['LDAP_DN']='cn={username},ou=people,ou=your-domain,dc=your-domain,dc=edu';
$GLOBALS['LIVEWHALE_CONFIG']['LDAP_SSL']=true;
$GLOBALS['LIVEWHALE_CONFIG']['LDAP_CONTACT_INFO']="Jane Smith at 555-555-5555 or jsmith@university.edu";

LDAP Settings

Name Description
LDAP_HOST Set this to the LDAP host. If the LDAP server is running on the same server as your web site, you may set this to “localhost”.
LDAP_PORT If the LDAP server is using a different port than the default, you may set it here.
LDAP_DN Set this to the base DN identifying LDAP users who should be allowed access to LiveWhale.
LDAP_SSL Set this to true if LDAP connections should be established with SSL, false if not.
LDAP_SEARCH_USER Set this to the DN that identifies the master user you wish to authenticate as to perform a subsequent search.
LDAP_SEARCH_PASS Set this to the password for the master user.
LDAP_SEARCH_FILTER By default, users are matched via the filter (cn={username}) but if you wanted to match the user-supplied username against a different field (such as sAMAccountName), you can deploy this setting to customize that filter.
LDAP_TLS Set this to true if LDAP connections should be established using TLS (LiveWhale 1.7+)
LDAP_CACERTFILE Connect using the specified cert file when using LDAP_SSL (LiveWhale 1.7+)
LDAP_CACERTDIR Connect using the specified cert directory when using LDAP_SSL (LiveWhale 1.7+)

The above assumes a LDAPs connection, but you can do this non-secure as well by using 389 for the port and leaving LDAP_SSL as false. Note that the DN has the search string with the {username} enclosed. LiveWhale automatically replaces {username} with that provided by the user attempting to login.

CAS Configuration

Starting with LiveWhale 1.6, Apereo CAS authentication is available. Below are the configuration settings for CAS login.

1
2
3
4
$GLOBALS['LIVEWHALE_CONFIG']['CAS_HOST']='http://my-cas-idp.myschool.edu'; // your CAS authentication server's host
$GLOBALS['LIVEWHALE_CONFIG']['CAS_PORT']=443; // optional, defaults to 443 if skipped
$GLOBALS['LIVEWHALE_CONFIG']['CAS_CONTEXT']='/cas'; // optional, defaults to /cas if skipped
$GLOBALS['LIVEWHALE_CONFIG']['CAS_CERTIFICATE_PATH']=''; // optional, but strongly recommended, should be full server path to intermediate certificate uploaded to the LiveWhale data directory

Once you are finished adding your configuration, set the LiveWhale login mode to use CAS in your config.php file

1
$GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='CAS';

Google Login Configuration

Before setting your login to use Google you must first set up the Google API keys. The Google API keys should be owned and managed by your institution and not set up through a personal account.

Setting up Google API keys

Configuring LiveWhale to use Google Authentication

  • Open ./livewhale/core/config.php for editing
  • Enter “google” for the LOGIN MODE (see below), as well as a domain to restrict to (if you\’re using Google Apps) and save your flle
1
2
$GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='google';
$GLOBALS['LIVEWHALE_CONFIG']['GOOGLE_DOMAIN']='domain.edu';
  • Next, open ./livewhale/client/global.config.php for editing
  • Add the client ID and client key obtained above to the following configuration for the Google API keys
1
2
3
4
$_LW->CONFIG['google_api_keys']=[ // API keys to enable Google authentication support
'client_id'=>'',
'client_secret'=>''
];

SAML/Shibboleth

LiveWhale 1.7 and later support native logins for SAML/Shibboleth using an integration with OneLogin.

In general, the LiveWhale team will assist with your SAML/Shibboleth integration during your roll-out, and connecting someone from your login team with support@livewhale.com should be sufficient to get that process started. Feel free to reach out if you are using an older login setup and would like to migrate to Shibboleth/SAML.

For more information about how SAML logins work in LiveWhale, read on.

  1. On the LiveWhale side, an x509 certificate gets generated and moved into the /livewhale/integrations/saml folder (creating it if need be), making sure both files are readable by the apache user.

    1
    2
    3
    4
    5
    sudo apt-get install libapache2-mod-shib2
    sudo shib-keygen
    sudo mv /etc/shibboleth/sp-cert.pem /home/mysite/www.mysite.edu/livewhale/integrations/saml/sp-cert.pem
    sudo mv /etc/shibboleth/sp-key.pem /home/mysite/www.mysite.edu/livewhale/integrations/saml/sp-key.pem
    sudo chown -R apache:apache /home/mysite/www.mysite.edu/livewhale/integrations/saml
  2. LiveWhale will extract the public x509 certificate from your IdP metadata and save it as /livewhale/integrations/saml/idp-cert.pem making sure it, too, is readable by the apache user.

  3. The following lines are added to your /livewhale/core/config.php

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    // $GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='SAML';
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_CERT']='saml/sp-cert.pem'; // path to your x509 certificate, in /livewhale/integrations
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_CERT_KEY']='saml/sp-key.pem'; // path to the private key for your x509 certificate, in /livewhale/integrations
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_ENTITY_ID']=''; // entityId for the IdP
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_URL']=''; // URL of where to send the authentication request. Look for SingleSignOnService (Redirect) in the provided IdP metadata.
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_LOGOUT_URL']=''; // (Optional) URL of where to send the authentication request. Look for SingleLogoutService in the provided IdP metadata.
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_CERT']='saml/idp-cert.pem'; // path for the IdP's public x509 certificate, in /livewhale/integrations
    // $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_ENCRYPTION_CERT']='saml/idp-encryption-cert.pem'; // optional: path for the IdP's encryption certificate, if different from the signing cert
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_USER_ATTRIBUTE']=''; // (optional) which user attribute to match up with a LiveWhale username; if empty, defaults to first received attribute; if true, bypasses attributes to use received NameId
    $GLOBALS['LIVEWHALE_CONFIG']['SAML_DEBUG']=false; // when true, shows received attributes rather than logging in
  4. In those configuration lines, these attributes from the IdP metadata are filled in: SAML_ENTITY_ID, SAML_IDP_URL, and SAML_IDP_LOGOUT_URL (optional).

  5. SP metadata will then be generated based on your settings at /live/saml/metadata – share this with the IdP for them to install on their server.

  6. Once that is installed, plug their details into your configuration (including saving their IdP cert if need be) and uncomment $GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='SAML'; to test.

  7. If logins aren’t working, try setting SAML_DEBUG to true to see what attributes (if any) you are receiving from the IdP. You may need to set SAML_USER_ATTRIBUTE if the attribute that matches up with the LiveWhale username isn’t the first one sent.

If the IdP has separate certificates for signing and encryption, save the signing cert as $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_CERT'] and save the encryption certificate as $GLOBALS['LIVEWHALE_CONFIG']['SAML_IDP_ENCRYPTION_CERT'].

Note: This integration might not work for every IdP, depending on configuration. Feel free to reach out to support@livewhale.com for assistance setting up Shibboleth/SAML logins.

Note: In some older versions of LiveWhale 1.7, /livewhale/integrations/saml was instead saved at /livewhale/data/saml. The correct location for those credential files going forward is /livewhale/integrations/saml.

Deprecated Configurations (SAML/Shibboleth)

SAML using mod_auth_mellon (Deprecated)

Note: This setup has been replaced by the native SAML/Shibboleth integration.

The configuration below is based on the mod_auth_mellon apache module, The module can be installed using the instructions at https://github.com/UNINETT/mod_auth_mellon/wiki/GenericSetup

mod_auth_mellon is a authentication module for Apache. It authenticates the user against a SAML 2.0 IdP, and grants access to directories depending on attributes received from the IdP.

Apache SSO Mod Mellon

The assumption is made that the following mellon configuration files will be placed in /etc/apache2/mellon:

  • idp-metadata.xml
  • mellon_create_metadata.sh
  • mod_auth_mellon.global.conf
  • mod_auth_mellon.local.conf
  • sp-metadata.xml
  • sp-private-key.pem
  • sp-cert.pem

Here are example configurations of the mellon conf files for LiveWhale SSO:

mod_auth_mellon.local.conf

1
2
3
4
5
6
7
8
9
10
11
12
13
<Location /livewhale/sso>
MellonEnable "auth"
MellonSPPrivateKeyFile /etc/apache2/mellon/sp-private-key.pem
MellonSPCertFile /etc/apache2/mellon/sp-cert.pem
MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
MellonEndpointPath /livewhale/sso/mellon
MellonSubjectConfirmationDataAddressCheck Off
MellonSecureCookie On
MellonMergeEnvVars On
MellonUser "REMOTE_USER"
MellonSetEnvNoPrefix "REMOTE_USER" "[Add your username/userid attribute here]"
</Location>

mod_auth_mellon.global.conf

1
2
3
4
5
6
7
<IfModule mod_auth_mellon.c>
MellonCacheSize 100
MellonLockFile "/var/run/mod_auth_mellon.lock"
MellonPostTTL 900
MellonPostSize 1073741824
MellonPostCount 100
</IfModule>

Configuration Steps

  • First, make sure that your server supports HTTPS and that your LiveWhale core/config.php has $GLOBALS['LIVEWHALE_CONFIG']['LOGIN_SECURE']=true;
  • Obtain the Identity Provider metadata from the SSO administrator and save it as /etc/apache2/mellon/idp-metadata.xml
  • Go to the mellon directory by running: sudo cd /etc/apache2/mellon
  • Run the following command and include the hostname in the [host] placeholder:
1
sudo ./mellon_create_metadata.sh sp.[host] https://[host]/livewhale/sso/mellon
  • Rename the sp.[host].key file by running: sudo mv sp.[host].key sp-private-key.pem
  • Rename the sp.[host].xml file by running: sudo mv sp.[host].xml sp-metadata.xml
  • Rename the sp.[host].cert file by running: sudo mv sp.[host].cert sp-cert.pem
  • Add the following to each SSL host in /etc/apache2/hosts-enabled (after the <IfModule mod_ssl.c>:
1
2
3
4
5
6
LoadModule auth_mellon_module /usr/lib/apache2/modules/mod_auth_mellon.so

<IfModule mod_auth_mellon.c>
Include /etc/apache2/mellon/mod_auth_mellon.global.conf
Include /etc/apache2/mellon/mod_auth_mellon.local.conf
</IfModule>
  • Submit the sp-metadata.xml file to the SSO administrator to install on the Identity Provider side
  • Once metadata is registered on the Identity Provider, place LiveWhale in SSO login mode
  • To confirm valid Apache configuration, run: sudo apachectl configtest
  • Run: sudo service apache2 restart

Deprecated: Shibboleth using mod_shib

Note: This setup has been replaced by the native SAML/Shibboleth integration.

The assumption is made that the Shibboleth server side configuration has been completed by your Shibboleth administrator. The instructions below outline the steps needed to be done on the client side for LiveWhale to use Shibboleth as a SSO solution.

  1. Install the Shibboleth client onto your LiveWhale webserver. Depending on your server setup this can be done using apt-get, yum, etc.. Typically the module’s configuration files will be installed in /etc/shibboleth.
    • Shibboleth server information should be configured at /etc/shibboleth/shibboleth2.xml
    • Certificates need to be configured at /etc/shibboleth/sp-cert.pem, /etc/shibboleth/sp-key.pem
  2. Set up the apache shibboleth configuration to load the shibboleth module (ex. shib.conf) below is an example apache shibboleth configuration file\

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    #Load the Shibboleth Module
    LoadModule mod_shib /usr/lib/apache2/modules/mod_shib_22.so

    # Used for example style sheet in error templates.
    <IfModule mod_alias.c>
    <Location /shibboleth-sp>
    Allow from all
    </Location>
    Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css
    </IfModule>

    #
    # Configure the module for content.
    #
    # You MUST enable AuthType shibboleth for the module to process
    # any requests, and there MUST be a require command as well. To
    # enable Shibboleth but not specify any session/access requirements
    # use "require shibboleth".
    <Location /livewhale/sso>
    AuthType shibboleth
    ShibRequestSetting requireSession 1
    require valid-user
    </Location>
  3. Switch the LiveWhale configuration to use SSO instead of the default local password setup. Do this by updating the /livewhale/core/config.php file and set the following the following Global variable to use ‘sso’

    1
    $GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='sso';

Reference Material

Creating a Custom Login Plugin

Advanced: If none of the above fit your criteria, you may wish to create your own login plugin.

  1. Create the following directory in your client modules directory: /livewhale/client/modules/login/includes/plugins
  2. In the directory above, add your own plugin (ie., my_plugin.php)
  3. Once you’ve created your login plugin and want to use it for LiveWhale authentication, edit your master config file, /livewhale/config.php, and set LOGIN_MODE to the name of your plugin (“my_plugin”)
  4. The format for your plugin is as follows:
1
2
3
4
5
6
7
8
9
<?php
// The filename and class name should match
class LiveWhaleLoginMyPlugin{
public function login($username, $password){
//Add your custom code to perform your authentication
//return true or false, according to whether the user authenticates
}
}
?>