= Installing the OTP login extension = {{{ #!html
Important information related to version 1.2 and higher!
To avoid locking everybody out of BASE it is recommended that the Password login form is enabled before starting the installation for the first time. Login to BASE and go to the Administrate ›› Plug-ins & extensions ›› Overview page. Locate the Login form customization extension point to find it. Once it has been verified that OTP login works properly the Password login form can be disabled if desired.
}}} == Installation and updating == 1. Download the latest `base-otp-x.y.tar.gz` file from the [wiki:net.sf.basedb.otp OTP login main page]. 2. Unpack the downloaded file to a directory of your choice. 3. If this is a FIRST-TIME INSTALLATION: A. Create a master password used for encrypting OTP secret keys (see below) B. Update the BASE database with additional columns in the users table (see below) 4. Make additional configuration settings (see below) 5. Copy the `base-otp.jar` file to your BASE plug-ins directory. Look in your `base.config` file if you don't know where this is. 6. Log in to BASE as an administrator and go to the '''Administrate ›› Plug-ins & Extensions ›› Overview''' page. 7. If this is a FIRST-TIME INSTALLATION: A. Verify that the '''Password login form''' is enabled. 8. Run the installation wizard and select to install `base-otp.jar`. 9. Done. ---- == FIRST-TIME INSTALLATION == Before installing the OTP login extension for the first time there are a few configuration steps that must be performed. Unless otherwise noted, these steps only need to be done the first time. === A. Create a master password === The master password is used as an encryption key for encrypting the OTP secret keys that are are assigned to user accounts. Note that all user accounts have their own secret keys for OTP and that they are randomly generated. Once the master password has been set it must not be changed since that will make all existing OTP keys inaccessible¹. 1. Open the `base-otp.properties` file. 2. Change the `master-password` setting to some other password. The usual recommendations about password length and complexity apply. 3. Move or copy the `base-otp.properties` file to the `WEB-INF/classes` directory of your BASE installation. If you have a copy in some other place, make sure that no other users can read it. ''¹) If, for some reason, the master password need to be changed then the `Users.otp_secretkey` column in the database must be nullified for all user accounts. There is no built-in wizard for this, but it can be done by executing the SQL below. After the reset, all users must then re-configure their OTP setup before they can login again.'' {{{ // For PostgreSQL, MySQL users should modify as needed update "Users" set "otp_secretkey"=NULL }}} === B. Update the BASE database with additional columns in the users table === 1. Move or copy the `otp-extended-properties.xml` file to the `WEB-INF/classes/extended-properties` directory. 2. Shut down the BASE server including any job agents. 3. Run the `updatedb.sh` script shipped with the BASE installation. This should create additional column in the `Users` table that are used to store OTP-related information. 4. Restart the BASE server and job agents. ---- == Additional configuration settings == There are some additional configuration settings that can be made in the `base-otp.properties` file. This step is optional. If you are installing multiple login managers on the same system you probably want to check the value for the `allow-other-authentication` setting. The authentication methods published by this extension are named `otp-only` and `otp+password`. You may need this when configuring the other login managers. '''Note! Since version 1.2 changes to the configuration file are automatically detected and applied. There is no longer any need to re-start the server.''' ==== login-method ==== Set the value to `otp+password` (the default) to require users to specify both the password and an OTP or to `otp-only` to only use an OTP. ==== no-otp ==== Comma- or whitespace- separated list of application ids for which OTP login should be disabled. For example, if you have installed the [wiki:net.sf.basedb.ftp FTP server] but do not want to use OTP for that: {{{ no-otp = net.sf.basedb.clients.ftp }}} ==== require-otp ==== Comma- or whitespace- separated list of application ids for which OTP login is required. Users that has not configured OTP login will not be able to use those clients. For example, to force all users of the web client to use OTP: {{{ require-otp = net.sf.basedb.clients.web }}} ==== allow-other-authentication (since 1.2) ==== Comma- or whitespace- separated list of other authentication methods that are allowed even if a user has configured OTP. Use `*` as a wildcard for all other authentication methods (including password authentication). Examples: {{{ # Also allow password authentication even if a user has OTP allow-other-authentication = password # Allow all other authentication methods allow-other-authentication = * # If the YubiKey login extension is also installed we can # allow users to use either OTP or YubiKey allow-other-authentication = yubikey }}}