diff --git a/docs/2/auth-schemes.md b/docs/2/auth-schemes.md index 77aad09..8621b74 100644 --- a/docs/2/auth-schemes.md +++ b/docs/2/auth-schemes.md @@ -23,7 +23,9 @@ The following authentication schemes are enabled by default: - A cookie-based "remember me" authentication scheme (`SimpleID\Auth\RememberMeAuthSchemeModule`) For additional [login verification](/docs/2/login-verification/), the OTP authentication scheme -(`SimpleID\Auth\OTPAuthSchemeModule`) can be enabled on top of the default modules. +(`SimpleID\Auth\OTPAuthSchemeModule`) and/or the WebAuthn +authentication scheme +(`SimpleID\Auth\WebAuthnAuthSchemeModule`) can be enabled on top of the default modules. The extensibility of SimpleID means an entirely different set of authentication schemes can be implemented. One such scheme is the [CertAuthSchemeModule](#certauth) distributed with diff --git a/docs/2/login-verification.md b/docs/2/login-verification.md index 5c389b1..3810bd4 100644 --- a/docs/2/login-verification.md +++ b/docs/2/login-verification.md @@ -9,20 +9,39 @@ eleventyNavigation: order: 20 --- -To further protect your profile, you can enable login verification. Login verification adds an extra layer of security using one-time passwords generated by another device (such as your phone). Thus in order to access your profile, an attacker will need to have access to your device as well as knowing your user name and password. +To further protect your profile, you can enable login verification. Login verification adds an extra layer of security using one-time passwords generated by another device (such as your phone or a security key). Thus in order to access your profile, an attacker will need to have access to your device as well as knowing your user name and password. + +## Supported login verification methods + +SimpleID supports two methods of login verification methods: + +* Time-based One-time Password (TOTP), which typically uses an authenticator app on a smart phone +* WebAuthn-based authentication, which uses a phyiscal security key. + +> [!NOTE] +> +> If you enable WebAuthn-based authentication, you will also enable support for [passkeys](/docs/2/passkeys), which allows you to log in without a password or additional login verification. ## What you need -You will need a device (such as a smartphone) that supports [RFC 6238](http://tools.ietf.org/html/rfc6238) Time-based One-time Password Algorithm. Examples of smartphone apps support this algorithm include: +For TOTP-based login verification, you will need a device (such as a smartphone) with an authenticator app that supports [RFC 6238](http://tools.ietf.org/html/rfc6238) Time-based One-time Password Algorithm. Examples of smartphone apps support this algorithm include: - Google Authenticator - Microsoft Authenticator - FreeOTP +For WebAuthn-based authentication, you will need a physical security key such as a Yubikey. + +> [!IMPORTANT] +> +> Non-hardware security keys such as Windows Hello and iCloud Keychain cannot be used for login verification. Instead, they can be used as [passkeys](/docs/2/passkeys). + ## How to enable -1. Login verification is implemented in an [authentication scheme module](/docs/2/auth-schemes) called OTPAuthSchemeModule. - To enable this module, open the `config.php` file and add `SimpleID\Auth\OTPAuthSchemeModule` under `modules`. +### TOTP-based login verification + +1. Login verification is implemented in [authentication scheme modules](/docs/2/auth-schemes). For TOTP-based login verification this is + `SimpleID\Auth\OTPAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`. 2. [Log in to SimpleID](/docs/2/login) 3. From the **My Profile** page, go to the **Login Verification** box, then click **Enable**. 4. Enter the key shown on the page into your device. If your device supports scanning QR codes, you can also scan the QR code shown. @@ -30,6 +49,17 @@ You will need a device (such as a smartphone) that supports [RFC 6238](http://to Login verification is then enabled. Every time you attempt to log in using this account, you will be prompted to enter the 6 digit verification code shown on your device. +### WebAuthn-based login verification + +1. Login verification is implemented in [authentication scheme modules](/docs/2/auth-schemes). For WebAuthn-based login verification this is + `SimpleID\Auth\WebAuthnAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`. +2. [Log in to SimpleID](/docs/2/login) +3. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Add**. +4. Enter a user-friendly name for the key, then click **Add security key**. +5. Follow the instructions on your device and insert your security key. + +Login verification is then enabled. Every time you attempt to log in using this account, you will be prompted to insert the security key (and enter a PIN if required). + ## How to disable 1. [Log in to SimpleID](/docs/2/login) diff --git a/docs/2/passkeys.md b/docs/2/passkeys.md new file mode 100644 index 0000000..da32e78 --- /dev/null +++ b/docs/2/passkeys.md @@ -0,0 +1,49 @@ +--- +layout: docs +title: Passkeys +permalink: /docs/2/passkeys/ +eleventyNavigation: + key: 2/passkeys + title: Passkeys + parent: 2/_using-simpleid + order: 25 +--- + +Passkeys allow you to log in without a password by using your biometrics or another mechanism. Passkeys can be saved to supported devices, such as a personal computer, a phone or a hardware security key. + +You can save a passkey to this device or another device, such as a phone or hardware security key. + +## What you need + +Passkeys are supported in the following devices: + +* laptops and personal computers with recent versions of Windows and macOS, when used with a supported web browser +* phones running recent versions of iOS or Android +* hardware security keys such as Yubikey + +## How to enable + +1. Passkey is implemented in [an authentication scheme module](/docs/2/auth-schemes). For this is + `SimpleID\Auth\WebAuthnAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`. + + > [!NOTE] + > + > Enabling WebAuthnAuthSchemeModule also enables support for [login verification](/docs/2/login-verification) using hardware security keys. + +2. To save a passkey, [log in to SimpleID](/docs/2/login) normally. + +3. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Add**. + +4. Enter a user-friendly name for the key, then click **Add passkey**. + +5. Follow the instructions on your device. + +Once a passkey is saved, you can log in by clicking on **Log in with a passkey** in the login page. + +## How to remove + +You can remove existing passkeys from your profile page. + +1. [Log in to SimpleID](/docs/2/login) +2. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Delete**. +