diff --git a/modules/restserver/src/main/resources/reference.conf b/modules/restserver/src/main/resources/reference.conf index 1e541b47..29b63dc1 100644 --- a/modules/restserver/src/main/resources/reference.conf +++ b/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). diff --git a/modules/webapp/src/main/elm/Messages/Page/UserSettings.elm b/modules/webapp/src/main/elm/Messages/Page/UserSettings.elm index df492a0b..33531d08 100644 --- a/modules/webapp/src/main/elm/Messages/Page/UserSettings.elm +++ b/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" } diff --git a/website/site/content/docs/configure/_index.md b/website/site/content/docs/configure/_index.md index 9651f81a..7ebb0950 100644 --- a/website/site/content/docs/configure/_index.md +++ b/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 diff --git a/website/site/content/docs/features/_index.md b/website/site/content/docs/features/_index.md index a54920b3..b5855066 100644 --- a/website/site/content/docs/features/_index.md +++ b/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 diff --git a/website/site/content/docs/webapp/totp-01.png b/website/site/content/docs/webapp/totp-01.png new file mode 100644 index 00000000..6e45101d Binary files /dev/null and b/website/site/content/docs/webapp/totp-01.png differ diff --git a/website/site/content/docs/webapp/totp-02.png b/website/site/content/docs/webapp/totp-02.png new file mode 100644 index 00000000..133ace34 Binary files /dev/null and b/website/site/content/docs/webapp/totp-02.png differ diff --git a/website/site/content/docs/webapp/totp-03.png b/website/site/content/docs/webapp/totp-03.png new file mode 100644 index 00000000..a0a022ac Binary files /dev/null and b/website/site/content/docs/webapp/totp-03.png differ diff --git a/website/site/content/docs/webapp/totp.md b/website/site/content/docs/webapp/totp.md new file mode 100644 index 00000000..8e34e64f --- /dev/null +++ b/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. │ +└─────────┴──────────────────────┘ +```