= How to use the !WebAuthn authentication extension =

== Logging in ==

Before it is possible to login with a !WebAuthn Security Key the server administrator need to register the key and connect it to the user account (see below). It is not possible for users to register the key by themselves. Depending on the capabilities of the security key, the administrator may enable password-less authentication.


=== Basic !WebAuthn ===

In the basic mode, the user has to specify the login and password and then verify the login by touching the security key.

 1. Start by entering the '''Login''' and '''Password''' information in the form.
 2. Press '''ENTER''' or click on the '''Login''' button.
 3. The browser should ask you to insert the security into an USB port (unless it is already inserted).
 4. Press the button on the security key (do not click on the '''Cancel''' button).
 5. You should now be logged in.

{{{
#!html
<div style="background-color: #fffff0; border: 2px solid #6060A0; border-radius: 5px; padding: 1em; max-width: 60em;">
<b>Note!</b><br>
The exact prompts and dialogs that the browser displays vary by the browser and operating system you are using. Below are some examples:
</div>
}}}

==== Newer Firefox, Chrome and Edge 101 on Windows 10 ====

|| '''Step 3: Prompting you for inserting a key''' || '''Step 4: Prompting you for touching the key''' ||
|| [[Image(insert-key.png)]] || [[Image(touch-key.png)]] ||


==== Older Firefox ====

|| '''Step 3 and 4: Prompting you for inserting and touching the key''' ||
|| [[Image(older-firefox.png)]] ||


=== Password-less authentication ===

If the security key supports it, the administrator may enable password-less authentication. For example, this is possible with the newer !YubiKey 5 models. This mode also requires that the security key is protected with a PIN.

 1. Start by selecting the '''!WebAuthn (password-less)''' login metod
 2. Click on the '''Login''' button.
 3. The browser should ask you to insert the security into an USB port (unless it is already inserted).
 4. Enter the PIN and press the button on the security key (do not click on the '''Cancel''' button).
 5. You should now be logged in.

|| '''Step 1: Password-less login''' || '''Step 4: Enter a PIN''' ||
|| [[Image(password-less-login.png)]] || [[Image(enter-pin.png)]] ||

== Assigning security keys to users ==

 1. To assign a !WebAuthn security to a user, the BASE administrator should
    locate that user in the '''Administrate->Users''' list and open the edit dialog.
 2. Switch to the '''!WebAuthn''' tab. This should state that no security key is enabled for 
    the account.
 3. Insert the security key into an USB port.
 4. Decide if password-less login should be enabled or not and click on the '''Register''' button.
 5. Press the button on the security for verification. If password-less login has been enabled, the user must also enter the PIN. If the security doesn't support password-less login, the browser should display an error message and the registration need to be re-started without the password-less login option.
 6. If the registration is successful the dialog should switch to reflect the
    fact that the account is now !WebAuthn-enabled. Take out the key and
    enter the serial number into the '''Serial #''' field (optional). Save!


== Unassign a security key ==

Click on the '''Remove''' in the '''!WebAuthn''' tab in the '''Edit user''' dialog. Save!

== Notes! ==

 1. It is possible to assign the same security key to more than one user account. This might be 
    practical for persons that have one regular account for daily usage and one account for 
    administrative needs. 
 2. The administrator may allow other authentication methods.