-
Notifications
You must be signed in to change notification settings - Fork 0
User registration and login
When you first run this app and access it with your browser, you will automatically be redirected to an URI like this: https://yourdomain.com/register/none. This specific URI only works as long as no users are registered. The user you register as will become the administrator user. Choose a very secure password for this user. The next step will ask you to set up your 2-Factor authentication token. More information on this in the next section.
Registration of additional users requires a registration token, created by an user with administrative privileges. These tokens can be created in the Admin menu at Registration tokens. Select a duration for how long the token should be valid and click the Add token button. If the user should only be able to log in with a manually created OTP token, check the OTP only checkbox. He will be able to configure 2nd factors, but they can't be used to authenticate.
The page will refresh and display the created token. Click on the token to generate a registration-URI that you can send to users whom you want to grant access. Registration is only possible with a valid token. Attempts to register with invalid tokens result in IP banning after multiple failed attempts.
Once a user is registered he is automatically logged in and redirected to the 2-Factor section of the Security settings. Without the second factor further logins are not possible. Hence this step should not be skipped if the user should be able to log in without manually created OTPs.
At the 2-Factor configuration you can set up either (multiple) FIDO2 / WebAuthn tokens or a single TOTP token. FIDO2 is recommended because it attaches authentication to a specific device. You can use TOTP as a fallback or alternative. But keep in mind that the secrets used for TOTP can be enrolled on multiple devices or shared in other ways.
To enroll your FIDO2 token enter a name for it, then click Add FIDO2 token. Follow the instructions displayed by your browser to complete the enrollment process. If no errors occurred, the token will be added to the table above.
FIDO2 / WebAuthn does not work without certificates. So however you deploy the app, make sure it can be accessed using an encrypted connection.
If you choose to use TOTP, click the Generate TOTP token button. You will be prompted to continue because this process will overwrite existing tokens from a previous enrollment (if you have added a TOTP token before). After confirming the prompt the page will refresh and you will see the Base32 secret the TOTP will be derived from during authentication. Depending on your authenticator you now either have to enter the Base32 secret, or you can scan the QR Code displayed below. If you are doing this from a mobile device, tapping the QR Code should automatically add the token to your authenticator application. The QR Code is based on the Provisioning URI you can find here as well. Use this URI if you want to create the QR Code manually.
The Secret / QR code will only be displayed until TOTP has been used at least once to authenticate (this initializes the token). This is done to prevent the user from sharing the secret later on. We can however not stop him from taking a screenshot of this data.
Later on the Base32 Secret box will display Initialized to indicate the active token.
The TOTP secret is encrypted before storing it to the database. The key for encryption is the one you pass when starting the application by using the environment variable FLASK_SECRET_KEY. If you don't pass this value, a random key is generated with each application start. Hence it will not be possible to decrypt the stored TOTP secrets anymore! In this case the Base32 Secret box will display Invalid.
TL;DR: TOTP requires FLASK_SECRET_KEY to be set as an environment variable at startup. Read this for more information about the key.
When accessing your webapp (without being logged in already), the user has to authenticate by providing his username and password.
If the user is coming from a device which is enrolled with FIDO2, he can just hit Login. If the username and password are correct, the browser will display the authentication dialog used to verify the device. This may include authentication with a PIN, fingerprint, NFC token etc.. If this was successful, the user will be logged in and redirected to the trigger list.
If the user uses TOTP for verification, the current TOTP-code from the authenticator has to be entered in the third text field. Usually authenticator apps allow to copy the code the the devices clipboard in some way, allowing the user to paste it without effort. Once this has been done, he can hit Login. If the username, password and TOTP code are correct, the user will be logged in and redirected to the trigger list.
TOTP relies on accurate system time on both client and server side.
TOTP codes have a rather short lifetime (30 seconds). If your authenticator app indicates that the current code will expire soon, wait may have to wait for the next iteration. In this app TOTP codes only pass verification if they match the one that is currently valid on the server, plus one before and one after. So one specific token has a total lifetime of 90 seconds.
If neither FIDO2 nor TOTP are configured OR the user is marked as OTP-only, the user requires a manually generated OTP. An administrator can create such tokens at OTP within the Admin menu. The user for which the OTP should be valid has to be selected from the list of users. Additionally the expiration time (default is 5 minutes) can be adjusted as required. After clicking Add token the page will refresh and display the newly generated token in the table at the top of the site. Clicking the token will create the full Login-URI the user has to access to be able to log in. Since there is no input field for the OTP token on the login site, the token has to be provided by the URI.
A user who is accessing the login site with such a token only has to enter his username and password to log in successfully. Authentication will fail is the token is invalid, expired or assigned to a different user.