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:

• LDAP
• CAS
• Shibboleth
• SAML
• Google

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

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

• Go to https://console.developers.google.com/
• Create project
• Enter new project
• Choose APIs & auth then choose Credentials
• Obtain a new client ID and client secret
• Click Edit Settings
• Add the following Authorized JavaScript Origins
  • http://your.website.edu
  • https://your.website.edu
• Add the following Authorized redirect URIs
  • http://your.website.edu/livewhale/?login&callback=google
  • https://your.website.edu/livewhale/?login&callback=google

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 supports native logins for SAML/Shibboleth using an integration with OneLogin.

Managed SAML/Shibboleth integrations

In general, the LiveWhale team assists with your SAML/Shibboleth integration during new site roll-outs, and connecting someone from your login team with your project team should be sufficient to get that process started. Feel free to reach out if you are using an older login setup and would like assistance migrating to Shibboleth/SAML. You’ll need to provide IdP metadata to get started.

Installing your own SAML/Shibboleth integration

Required skills include:

• SFTPing into your LiveWhale server
• Editing PHP configuration files
• Running Linux command-line tools from your own computer (to generate x509 certificate)
• Reading your own SAML IdP metadata to extract certificate, EntityID, SingleSignOnService URL

To install your own LiveWhale SAML/Shibboleth integration, follow these steps:

1. On the LiveWhale side, the process begins by generating a new x509 certificate uploading it into the /livewhale/integrations/saml folder (creating it if need be). Run these command-line controls from any Linux/Apache server you have SSH access to that supports mod-shib2:
   
   sudo apt-get install libapache2-mod-shib2
   sudo shib-keygen
   
   Afterwards, download the newly generated sp-key.pem and sp-cert.pem (by default they’re usually in /etc/shibboleth/) and upload them both via SFTP to /livewhale/integrations/saml/.

2. Extract the public x509 certificate from your IdP metadata and save it as /livewhale/integrations/saml/idp-cert.pem (additionally, if your IdP metadata specifies a separate encryption cert, save that as /livewhale/integrations/saml/idp-encryption-cert.pem).

3. Add the following lines to your /livewhale/core/config.php file:

   // $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_REMOVE_REQUESTED_AUTH_CONTEXT']=true; // (optional, LiveWhale 2.11+) when true, any auth context is allowed. Otherwise, requestedAuthnContext defaults to urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
   $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 based on the values from the IdP metadata: 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 whoever manages your IdP for them to install on their end.

6. Once that is installed, and the details from the IdP metadata are complete in livewhale/core/config.php, uncomment $GLOBALS['LIVEWHALE_CONFIG']['LOGIN_MODE']='SAML'; to enable.

7. With the connection in place, setting SAML_DEBUG to true will show what attributes (if any) you are receiving from the IdP. On a successful login handshake with SAML_DEBUG=true, instead of logging in to LiveWhale, you’ll be shown a black-and-white debug screen which lists the received NameID as well as each attribute sent by the IdP. Using this debug screen, set the SAML_USER_ATTRIBUTE configuration so that the desired attribute gets matched up and used for your LiveWhale usernames.

SAML Attributes

The only attribute your IdP needs to release is LiveWhale is username. This gets matched up with the usernames of all LiveWhale editors on login. Sometimes a separate attribute may not even be necessary to send, if you see “Identified user:” in the debug screen matching your username, you can set SAML_USER_ATTRIBUTE to true.

Optionally, if you do send additional attributes, those can be tracked with login cookies and used in custom code to show special behaviors based on user name, email, type, etc. See AUTH_ATTRIBUTES for instructions and examples on how to get started with tracking custom login attributes.