mirror of
https://github.com/TheAnachronism/docspell.git
synced 2024-11-13 02:31:10 +00:00
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
|
+++
|
||
|
|
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. │
|
||
|
|
└─────────┴──────────────────────┘
|
||
|
|
```
|