Skip to content

Commit 5d433bf

Browse files
kelvinmokelvinmo
authored
Merge pull request #106 from simpleid/features/passkeys
Add documentation on passkeys
2 parents 756f113 + 4c76406 commit 5d433bf

3 files changed

Lines changed: 86 additions & 5 deletions

File tree

‎docs/2/auth-schemes.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@ The following authentication schemes are enabled by default:
2323
- A cookie-based "remember me" authentication scheme (`SimpleID\Auth\RememberMeAuthSchemeModule`)
2424

2525
For additional [login verification](/docs/2/login-verification/), the OTP authentication scheme
26-
(`SimpleID\Auth\OTPAuthSchemeModule`) can be enabled on top of the default modules.
26+
(`SimpleID\Auth\OTPAuthSchemeModule`) and/or the WebAuthn
27+
authentication scheme
28+
(`SimpleID\Auth\WebAuthnAuthSchemeModule`) can be enabled on top of the default modules.
2729

2830
The extensibility of SimpleID means an entirely different set of authentication schemes can
2931
be implemented. One such scheme is the [CertAuthSchemeModule](#certauth) distributed with

‎docs/2/login-verification.md‎

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,57 @@ eleventyNavigation:
99
order: 20
1010
---
1111

12-
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.
12+
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.
13+
14+
## Supported login verification methods
15+
16+
SimpleID supports two methods of login verification methods:
17+
18+
* Time-based One-time Password (TOTP), which typically uses an authenticator app on a smart phone
19+
* WebAuthn-based authentication, which uses a phyiscal security key.
20+
21+
> [!NOTE]
22+
>
23+
> 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.
1324
1425
## What you need
1526

16-
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:
27+
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:
1728

1829
- Google Authenticator
1930
- Microsoft Authenticator
2031
- FreeOTP
2132

33+
For WebAuthn-based authentication, you will need a physical security key such as a Yubikey.
34+
35+
> [!IMPORTANT]
36+
>
37+
> 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).
38+
2239
## How to enable
2340

24-
1. Login verification is implemented in an [authentication scheme module](/docs/2/auth-schemes) called OTPAuthSchemeModule.
25-
To enable this module, open the `config.php` file and add `SimpleID\Auth\OTPAuthSchemeModule` under `modules`.
41+
### TOTP-based login verification
42+
43+
1. Login verification is implemented in [authentication scheme modules](/docs/2/auth-schemes). For TOTP-based login verification this is
44+
`SimpleID\Auth\OTPAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`.
2645
2. [Log in to SimpleID](/docs/2/login)
2746
3. From the **My Profile** page, go to the **Login Verification** box, then click **Enable**.
2847
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.
2948
5. Enter the 6 digit verification code shown on your device and click **Verify**.
3049

3150
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.
3251

52+
### WebAuthn-based login verification
53+
54+
1. Login verification is implemented in [authentication scheme modules](/docs/2/auth-schemes). For WebAuthn-based login verification this is
55+
`SimpleID\Auth\WebAuthnAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`.
56+
2. [Log in to SimpleID](/docs/2/login)
57+
3. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Add**.
58+
4. Enter a user-friendly name for the key, then click **Add security key**.
59+
5. Follow the instructions on your device and insert your security key.
60+
61+
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).
62+
3363
## How to disable
3464

3565
1. [Log in to SimpleID](/docs/2/login)

‎docs/2/passkeys.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
layout: docs
3+
title: Passkeys
4+
permalink: /docs/2/passkeys/
5+
eleventyNavigation:
6+
key: 2/passkeys
7+
title: Passkeys
8+
parent: 2/_using-simpleid
9+
order: 25
10+
---
11+
12+
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.
13+
14+
You can save a passkey to this device or another device, such as a phone or hardware security key.
15+
16+
## What you need
17+
18+
Passkeys are supported in the following devices:
19+
20+
* laptops and personal computers with recent versions of Windows and macOS, when used with a supported web browser
21+
* phones running recent versions of iOS or Android
22+
* hardware security keys such as Yubikey
23+
24+
## How to enable
25+
26+
1. Passkey is implemented in [an authentication scheme module](/docs/2/auth-schemes). For this is
27+
`SimpleID\Auth\WebAuthnAuthSchemeModule`. To enable this module, open the `config.php` file and add the appropriate module names under `modules`.
28+
29+
> [!NOTE]
30+
>
31+
> Enabling WebAuthnAuthSchemeModule also enables support for [login verification](/docs/2/login-verification) using hardware security keys.
32+
33+
2. To save a passkey, [log in to SimpleID](/docs/2/login) normally.
34+
35+
3. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Add**.
36+
37+
4. Enter a user-friendly name for the key, then click **Add passkey**.
38+
39+
5. Follow the instructions on your device.
40+
41+
Once a passkey is saved, you can log in by clicking on **Log in with a passkey** in the login page.
42+
43+
## How to remove
44+
45+
You can remove existing passkeys from your profile page.
46+
47+
1. [Log in to SimpleID](/docs/2/login)
48+
2. From the **My Profile** page, go to the **Passkeys and security keys** box, then click **Delete**.
49+

0 commit comments

Comments
 (0)