Token fixes (#13175)

* Prevent junk token from bypassing MFA

* updated docs

* Fix read-only token fields

* Fix API version ref

docs/docs/api/index.md

@@ -51,6 +51,9 @@ Users can authenticate against the API using basic authentication - specifically
 
 Basic authentication attempts might run into rate limits during authentication on busy instances, as this is a likely place of attacks. Prefer Token or OAuth2 authentication instead.
 
+!!! warning "Multi factor authentication"
+    Basic authentication is a single factor, so it is refused for users who have [multi factor authentication](../settings/MFA.md) configured, and for all users while MFA is enforced. These users must use a token (generated in the user interface) or OAuth2 instead. See [error code INVE-W20](../settings/error_codes.md#inve-w20).
+
 ### Tokens
 
 Each user is assigned an authentication token which can be used to access the API. This token is persistent for that user (unless invalidated by an administrator) and can be used across multiple sessions.
@@ -69,6 +72,11 @@ There is a guided process to generate, view and revoke access tokens in the `Sec
 
 Alternatively the API also issues tokens. Perform a GET request to `/api/user/me/token/`. No data are required, but a valid username / password combination must be supplied in the authentication headers. It is recommended to also send a name that identifies the token. The Name is also used for re-issuance of tokens when tokens are re-requested.
 
+!!! warning "Users with multi factor authentication"
+    Requesting a token with a basic authentication request is not possible for users with [MFA](../settings/MFA.md) configured, or while MFA is enforced (see [Basic Auth](#basic-auth)). These users should generate a token in the `Security` section of the user settings.
+
+    Calls to this endpoint by a user with MFA configured also require a recent login, so a token cannot be used to issue a new token. Otherwise, the server responds with `HTTP 401` and the id `reauthentication_required`.
+
 !!! info "Credentials"
 	Ensure that a valid username:password combination are supplied as a **basic authorization header**.
 
@@ -89,6 +97,9 @@ After reception of a valid authentication token, it can be subsequently used to
 
 The token value sent to the server must be of the format `Token <TOKEN-VALUE>` (without the `<` and `>` characters).
 
+!!! info "Tokens and MFA"
+    A token is a bearer credential - requests made with a valid token are not challenged for a second factor. While [MFA is enforced](../settings/MFA.md#configuration), tokens belonging to users who have not set up MFA are refused. They work again once the user sets up MFA.
+
 **Example: Javascript**
 ```javascript
 var token = "MY-TOKEN-VALUE-HERE";

docs/docs/api/python/index.md

@@ -44,6 +44,9 @@ MY_PASSWORD = 'not_my_real_password'
 api = InvenTreeAPI(SERVER_ADDRESS, username=MY_USERNAME, password=MY_PASSWORD)
 ```
 
+!!! warning "Multi factor authentication"
+    Username/password authentication is refused for users with [MFA](../../settings/MFA.md) configured, and for all users while MFA is enforced. Generate a token in the `Security` section of the user settings and use [token auth](#token-auth) instead.
+
 #### Token Auth
 
 Alternatively, if you already have an access token:

docs/docs/concepts/threat_model.md

@@ -29,7 +29,7 @@ Deploying InvenTree to production requires to knowledge of the security assumpti
 ## Possible Attack Vectors
 
 1. Malicious plugins or templates can overwrite or delete files on the server, bypass security checks, or leak sensitive information.
-2. Token phishing attacks can be used to impersonate users. Tokens are not scoped to specific IPs or devices. Limit their usage and use lowest possible user permissions.
+2. Token phishing attacks can be used to impersonate users. Tokens are not scoped to specific IPs or devices. Limit their usage and use lowest possible user permissions. API tokens are bearer credentials and are not challenged for a second factor on use - a leaked token gives access without the user's MFA device until it is revoked or expires.
 3. Malicious file uploads. Attachments are served (by default) under the same domain as the backend - this can lead to XSS attacks.
 
 There are various checks to gate against common attack vectors but above vectors are explicitly not addressed as they require organisational policies and procedures to mitigate.

docs/docs/settings/MFA.md

@@ -18,4 +18,14 @@ To make MFA mandatory for all users:
 
 Password based [basic authentication](../api/index.md#basic-auth) against the API is refused for users with MFA configured, and for all users while MFA is enforced. API clients should use tokens (generated in the user interface) or OAuth2 instead.
 
+While MFA is enforced:
+
+- Users without MFA must set it up before they can use the web interface or API with their session.
+- [API tokens](../api/index.md#tokens) cannot be requested until MFA is set up.
+- Existing API tokens of users without MFA are refused. They are not deleted, and work again once the user sets up MFA.
+
+Enabling enforcement ends all existing user sessions immediately.
+
+API tokens are bearer credentials: a valid token is not challenged for a second factor on each request. Users with MFA configured can only request a token via the API shortly after logging in (including their second factor). Treat tokens like passwords and revoke any that may have been exposed. Administrators who enable enforcement on an existing instance should review the issued tokens in the [Admin Center](../settings/admin.md#admin-center).
+
 A user can lock themselves out if they lose access to both the device with their TOTP app and their backup tokens. An admin can delete their tokens from the Database Admin interface (they exist under the 'TOTP devices' / 'static devices' models). This should be a last resort and only done by people knowledgeable about the [Database Admin interface](../settings/db_admin.md), as changes there might circumvent InvenTree's business and security logic.