Changes between Initial Version and Version 1 of net.sf.basedb.webauthn/install

Timestamp:

Jun 2, 2022, 1:39:41 PM (23 months ago)

Author:

Nicklas Nordborg

Comment:

Created installation instructions

net.sf.basedb.webauthn/install

@@ +1 @@
+= Installing the !WebAuthn authentication extension =
+
+{{{
+#!html
+<div style="background-color: #fffff0; border: 2px solid #A0A000; border-radius: 5px; padding: 1em; max-width: 60em;">
+<b>Important information before installing!</b>
+<br>
+To avoid locking everybody out of BASE it is recommended that the <b>Password login form</b> is enabled before starting the installation for the first time. Login to BASE and go to the <b>Administrate ›› Plug-ins & extensions ›› Overview</b> page. Locate the <b>Login form customization</b> extension point to find it. Once it has been verified that WebAuthn login works properly the <b>Password login form</b> can be disabled if desired.
+</div>
+}}}
+
+
+== Installation and updating ==
+
+ 1. Download the latest `webauthn-x.y.tar.gz` file from the [wiki:net.sf.basedb.webauthn WebAuthn main page].
+ 2. Unpack the downloaded file to a directory of your choice.
+ 3. If this is a FIRST-TIME INSTALLATION:
+    A. Update the BASE database with additional columns in the users table (see below)
+ 4. Make additional configuration settings (see below)
+ 5. Copy the `webauthn.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 `webauthn.jar`.
+ 9. Done
+ 
+
+----
+
+
+== FIRST-TIME INSTALLATION ==
+
+Before installing the !WebAuthn 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. Update the BASE database with additional columns in the users table ===
+
+ 1. Move or copy the `webauthn-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 !WebAuthn-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 `webauthn.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 method published by this extension is named `webauthn`. You may need this when configuring the other login managers.
+
+'''Note! Changes to the configuration file are automatically detected and applied. There is no need to re-start the server.'''
+
+==== no-webauthn ====
+Comma- or whitespace- separated list of application ids for which !WebAuthn login should be disabled. For example, if you have installed the [wiki:net.sf.basedb.ftp FTP server] but do not want to use !WebAuthn for that: 
+{{{
+no-webauthn = net.sf.basedb.clients.ftp
+}}}
+
+==== require-webauthn ==== 
+Comma- or whitespace- separated list of application ids for which !WebAuthn login is required. Users without a !WebAuthn Security Key will not be able to use those clients. For example, to force all users of the web client to use !WebAuthn:
+{{{
+require-webauthn = net.sf.basedb.clients.web
+}}}
+
+==== allow-other-authentication ====
+Comma- or whitespace- separated list of other authentication methods that are allowed even if a user has configured a !WebAuthn Security Key. Use `*` as a wildcard for all other authentication methods (including password authentication). Examples:
+
+{{{
+# Also allow password authentication even if a user has a security key
+allow-other-authentication = password
+
+# Allow all other authentication methods
+allow-other-authentication = *
+
+# If the YubiKey and/or OTP login extension is also installed we can 
+# allow users to use either WebAuthn, YubiKey or OTP (with or without password)
+allow-other-authentication = otp-only otp+password yubikey
+}}}
+
+=== relying-party-id ===
+
+This ID is typically the name of the webserver that the browser connects to. This is is typically picked up automatically, but if that doesn't work it is possible to specify the correct name here.
+
+=== relying-party-allow-origin-port ===
+
+If the port number is not the default https port, this flag need to be enabled.
+
+=== relying-party-allow-origin-subdomain ===
+
+This flag can be set to allow subdomains to the relying-party-id value. 
+
+=== relying-party-disable-signature-counter ===
+
+If this flag is set, the signature counter is not verified. The counter is intended to prevent replay attacks but not all security keys support it.