Using Security keys on Codeberg (#367)

This PR adds docs on WebAuthn usage on Codeberg. It attempts to cover:
- using WebAuthn as a 2FA option on web logins
- using FIDO2 over SSH using the OpenSSH client

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/367
Co-authored-by: Alex <alex@blueselene.com>
Co-committed-by: Alex <alex@blueselene.com>

content/security/2fa.md

@@ -16,28 +16,30 @@ That way, your account cannot be compromised even if your password gets compromi
 
 ## How to set up two-factor authentication
 
-### Prerequisites
+### TOTP
+
+#### Prerequisites
 
 You will need an authenticator app installed on your phone.
 
 If you don't already have an authenticator app and you're not sure which app to use, have a look at Aegis Authenticator
 ([F-Droid](https://f-droid.org/de/packages/com.beemdevelopment.aegis/) | [Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US)) or Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276)).
 
-### Step 1: Navigate to your user settings
+#### Step 1: Navigate to your user settings
 
 <picture>
   <source srcset="/assets/images/security/user-settings.webp" type="image/webp">
   <img src="/assets/images/security/user-settings.png" alt="User Settings">
 </picture>
 
-### Step 2: Navigate to the Security tab and click on the Enroll button
+#### Step 2: Navigate to the Security tab and click on the Enroll button
 
 <picture>
   <source srcset="/assets/images/security/2fa/security-settings.webp" type="image/webp">
   <img src="/assets/images/security/2fa/security-settings.png" alt="Security Settings">
 </picture>
 
-### Step 3: Scan the QR code and enter the verification code
+#### Step 3: Scan the QR code and enter the verification code
 
 <picture>
   <source srcset="/assets/images/security/2fa/qr-scan.webp" type="image/webp">
@@ -46,7 +48,7 @@ If you don't already have an authenticator app and you're not sure which app to
 
 After scanning the QR code with your app, enter the six-digit code displayed in your app into the "Passcode" field of the settings form, then click "Verify".
 
-### Step 4: Store your scratch token in a safe place
+#### Step 4: Store your scratch token in a safe place
 
 If your phone ever breaks, gets lost or gets stolen, you can recover your account using the scratch token.
 
@@ -59,12 +61,54 @@ This is shown to you right after setting up 2FA:
 
 Please store this token in a safe place.
 
-### Step 5: Done!
+#### Step 5: Done!
 
 That's it - you have now configured two-factor authentication for your account.
 
 From now on, each time you log into Codeberg you will be asked for an authentication code from your app, adding an extra layer of security over just using a password.
 
+### WebAuthn
+
+If TOTP is configured, you can also add security keys to your account. These security keys are hardware devices that securely store cryptographic keys. They are either integrated on your device, like some phones' fingerprint scanners, or connect to it via USB or NFC.
+
+While you'll be able to recover access to your account using TOTP if your key breaks, if you can, you should add at least 2 security keys.
+
+#### Step 1: Navigate to your user settings
+
+<picture>
+  <source srcset="/assets/images/security/user-settings.webp" type="image/webp">
+  <img src="/assets/images/security/user-settings.png" alt="User Settings">
+</picture>
+
+#### Step 2: Go to the security tab and locate the Security Keys section
+
+Look for `Security` on the list of settings.
+
+The `Security Keys` section should be right under the `Two-Factor Authentication` section where you configured TOTP.
+
+#### Step 3: Give your key a nickname
+
+<picture>
+  <source srcset="/assets/images/security/webauthn-nick.webp" type="image/webp">
+  <img src="/assets/images/security/webauthn-nick.png" alt="WebAuthn key nickname input">
+</picture>
+
+Choose a nickname for your key and input it on the `Nickname` input.
+
+#### Step 4: Follow your browser's instructions
+
+Once you've decided on a nickname, click `Add Security Key` right under the `Nickname` input and follow your browser's instructions.
+
+#### Step 5: Done!
+
+WebAuthn is now configured for your account! Now, when you sign in, you'll be given a choice between using TOTP or WebAuthn.
+
+{% admonition "Tip" %}
+
+You can very likely use your WebAuthn security key to secure your SSH key, learn more about this on (Adding an SSH key to your account)[/security/ssh-key]).
+
+{% endadmonition %}
+
 ## Personal access token
 
 If you push to Codeberg via HTTP (see [Clone & Commit via HTTP](/git/clone-commit-via-http)), an extra step will be needed to create a personal access token. This token will replace your normal password (+ authentication code) on Codeberg.

content/security/ssh-key.md

@@ -35,6 +35,24 @@ It is recommended to use one key per client. This means that if you access your
 
 Your private key can be protected by a passphrase. This adds a layer of authentication that increases security. Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection. It is recommended to keep your private key safe and - well - private.
 
+### FIDO2 with OpenSSH
+
+1. Connect your security key and open a terminal
+
+2. Paste the text below
+
+    ```shell
+    ssh-keygen -t ed25519-sk  
+    ```
+
+3. If you have set one on your key, you'll be prompted for your FIDO2 PIN. Enter it to continue
+
+4. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>. This accepts the default file location.
+
+5. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.
+
+Keep in mind that now, every time you wish to use Codeberg over SSH, you must have your security key plugged in and will be prompted to touch it to continue.
+
 ## Add the SSH key to Codeberg
 
 1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. You can identify it by the `.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`.