Document TOTP

modules/restserver/src/main/resources/reference.conf

@@ -66,31 +66,31 @@ docspell.server {
   #
   # Multiple authentication providers can be defined. Each is
   # configured in the array below. The `provider` block gives all
-  # details necessary to authenticate agains an external OIDC or OAuth
-  # provider. This requires at least two URLs for OIDC and three for
-  # OAuth2. The `user-url` is only required for OIDC, if the account
-  # data is to be retrieved from the user-info endpoint and not from
-  # the JWT token. The access token is then used to authenticate at
-  # the provider to obtain user info. Thus, it doesn't need to be
-  # validated here and therefore no `sign-key` setting is needed.
-  # However, if you want to extract the account information from the
-  # access token, it must be validated here and therefore the correct
-  # signature key and algorithm must be provided. This would save
-  # another request. If the `sign-key` is left empty, the `user-url`
-  # is used and must be specified. If the `sign-key` is _not_ empty,
-  # the response from the authentication provider is validated using
-  # this key.
+  # details necessary to authenticate against an external OIDC or
+  # OAuth provider. This requires at least two URLs for OIDC and three
+  # for OAuth2. When using OIDC, the `user-url` is only required if
+  # the account data is to be retrieved from the user-info endpoint
+  # and not from the JWT token. For the request to the `user-url`, the
+  # access token is then used to authenticate at the provider. Thus,
+  # it doesn't need to be validated here and therefore no `sign-key`
+  # setting is needed. However, if you want to extract the account
+  # information from the access token, it must be validated here and
+  # therefore the correct signature key and algorithm must be
+  # provided. If the `sign-key` is left empty, the `user-url` is used
+  # and must be specified. If the `sign-key` is _not_ empty, the
+  # response from the authentication provider is validated using this
+  # key.
   #
   # After successful authentication, docspell needs to create the
   # account. For this a username and collective name is required. The
-  # username is defined by the `user-key` setting. The `user-key` is
-  # used to search the JSON structure, that is obtained from the JWT
-  # token or the user-info endpoint, for the login name to use. It
-  # traverses the JSON structure recursively, until it finds an object
-  # with that key. The first value is used.
+  # account name is defined by the `user-key` and `collective-key`
+  # setting. The `user-key` is used to search the JSON structure, that
+  # is obtained from the JWT token or the user-info endpoint, for the
+  # login name to use. It traverses the JSON structure recursively,
+  # until it finds an object with that key. The first value is used.
   #
-  # There are the following ways to specify how to retrieve the full
-  # account id depending on the value of `collective-key`:
+  # The `collective-key` can be used in multiple ways and both can
+  # work together to retrieve the full account id:
   #
   # - If it starts with `fixed:`, like "fixed:collective", the name
   #   after the `fixed:` prefix is used as collective as is. So all
@@ -100,15 +100,15 @@ docspell.server {
   #   value after the prefix is used to search the JSON response for
   #   an object with this key, just like it works with the `user-key`.
   #
-  # - If it starts with `account:`, like "account:ds-account", it
-  #   works the same as `lookup:` only that the value is interpreted
-  #   as the full account name of form `collective/login`. The
-  #   `user-key` value is ignored in this case.
+  # - If it starts with `account:`, like "account:demo", it works the
+  #   same as `lookup:` only that the value is interpreted as the full
+  #   account name of form `collective/login`. The `user-key` value is
+  #   ignored in this case.
   #
   # If these values cannot be obtained from the response, docspell
-  # fails the authentication by denying access. It is then assumed
-  # that the successfully authenticated user has not enough
-  # permissions to access docspell.
+  # fails the authentication. It is then assumed that the successfully
+  # authenticated user at the OP has not enough permissions to access
+  # docspell.
   #
   # Below are examples for OpenID Connect (keycloak) and OAuth2
   # (github).

modules/webapp/src/main/elm/Messages/Page/UserSettings.elm

@@ -84,7 +84,7 @@ gb =
             or to just leave it there. In the latter case you should
             adjust the schedule to avoid reading over the same mails
             again."""
-    , otpMenu = "Two Factor"
+    , otpMenu = "Two Factor Authentication"
     }
 
 

website/site/content/docs/configure/_index.md

@@ -342,7 +342,7 @@ The `session-valid` determines how long a token is valid. This can be
 just some minutes, the web application obtains new ones
 periodically. So a rather short time is recommended.
 
-### OpenID Connect / OAuth2
+## OpenID Connect / OAuth2
 
 You can integrate Docspell into your SSO solution via [OpenID
 Connect](https://openid.net/connect/) (OIDC). This requires to set up

website/site/content/docs/features/_index.md

@@ -36,6 +36,8 @@ description = "A list of features and limitations."
 - [OpenID Connect](@/docs/configure/_index.md#openid-connect-oauth2)
   support allows Docspell to integrate into your SSO setup, for
   example with keycloak.
+- Two-Factor Authentication using [TOTP](@/docs/webapp/totp.md) built
+  in
 - mobile-friendly Web-UI with dark and light theme
 - [Create anonymous
   “upload-urls”](@/docs/webapp/uploading.md#anonymous-upload) to
@@ -76,8 +78,6 @@ description = "A list of features and limitations."
     link and send the file to docspell
   - [SMTP Gateway](@/docs/tools/smtpgateway.md): Setup a SMTP server
     that delivers mails directly to docspell.
-  - [Paperless Import](@/docs/tools/paperless-import.md) for importing
-    your data from paperless
 - License: AGPLv3
 
 

website/site/content/docs/webapp/totp.md

@@ -0,0 +1,79 @@
++++
+title = "Two-Factor Authentication"
+weight = 110
+[extra]
+mktoc = true
++++
+
+Docspell has built-in support for two-factor (2FA) authentication
+using
+[TOTP](https://en.wikipedia.org/wiki/Time-based_One-Time_Password)s.
+For anything more, consider a dedicated account management tool and
+[OpenID Connect](@/docs/configure/_index.md#openid-connect-oauth2).
+
+# Setup
+
+A user can enable a TOTP as a second factor in their user settings. It
+is required to have some external device to hold the shared secret. A
+popular way is using your phone. Some Android apps are for example
+[Aegis](https://f-droid.org/en/packages/com.beemdevelopment.aegis/) or
+[andOTP](https://f-droid.org/en/packages/org.shadowice.flocke.andotp/);
+and there are others as well.
+
+In user settings, go to _Two Factor Authentication_ and click on
+_Activate two-factor authentication_. This then shows you a QR code:
+
+{{ figure(file="totp-01.png") }}
+
+Open the app (or whatever you use) and scan the QR code. A new account
+is created and a 6-digit code will be shown to you. Enter this code in
+the box below to confirm.
+
+If you cannot scan the QR code, click on the "eye icon" to reveal the
+secret that you then need to type/copy. This secret will never be
+shown again. Should you loose it (or your device where it is saved),
+you cannot log in anymore. See below for how to get into your account
+in this case.
+
+Once you typed in the code, the 2FA is enabled.
+
+{{ figure(file="totp-02.png") }}
+
+When you now login, a second login form will be shown where you must
+now enter a one time password from the device.
+
+# Remove 2FA
+
+If you go to this page with 2FA enabled (refresh the page after
+finishing the setup), you can disable it. The secret will be removed
+from the database.
+
+It shows a form that allows you to disable 2FA again, but requires you
+to enter a one time password.
+
+{{ figure(file="totp-03.png") }}
+
+If you have successfully disabled 2FA, you'll see the first screen
+where you can activate 2FA. You can remove the account from your
+device. Should you want to go back to 2FA, you need to go through the
+setup again and create a new secret.
+
+# When secret is lost
+
+Should you loose your device where the secret is stored, you cannot
+log into docspell anymore. In this case you can use the [command line
+client](@/docs/tools/cli.md) to execute an admin command that removes
+2FA for a given user.
+
+For this to work, you need to [enable the admin
+endpoint](@/docs/configure/_index.md#admin-endpoint). Then execute the
+`disable-2fa` admin command and specify the complete account.
+
+```
+$ dsc admin -a test123 disable-2fa --account demo
+┌─────────┬──────────────────────┐
+│ success │ message              │
+├─────────┼──────────────────────┤
+│ true    │ TOTP setup disabled. │
+└─────────┴──────────────────────┘
+```