Skip to main content

Local Authentication

Cafe Variome V4 uses a local authentication system by default. This means that user credentials are stored in the local database and managed by Cafe Variome itself. All users must have a local account to access the system. Meanwhile, external authentication methods (e.g., OIDC) can be configured if needed. The remote accounts will be linked to local accounts for authorisation purposes. All permissions are managed locally by each Cafe Variome instance.

User Roles​

There are three user roles defined in Cafe Variome V4:

  • User: A regular user who can view his own settings, and can be configured to query on data sources as per the access group settings.
  • Admin: An administrator who can manage system settings, users, and data sources. Admins can query on all data sources, because they are able to assign themselves to any access group anyway, so the access group settings do not apply to them.
  • Super Admin: In addition to the admin capabilities, a super admin can manage debug level settings and bypass certain system restrictions. The first account created during the initial setup is assigned the super admin role by default. It's recommended to have as few super admins as possible for security reasons, and keep the super admin role for emergency use only.

User Registration and Management​

If registration is enabled, new users can sign up for an account through the registration page. By default, new users are assigned the "User" role and have no access to any data sources until an admin assigns them to appropriate access groups. The registration flow is as follows:

  • User fills out the registration form with necessary details (e.g., username, email, password).
  • Backend receives the registration request, checks for existing usernames/emails, and creates a new user record in the database with the "User" role. The user password is hashed with Argon2 before storage.
  • If the email service is configured, a verification email is sent to the user with a link to verify their email address. If not, the user account is directly activated.
  • User clicks the verification link, which sends a request to the backend to verify the email address and activate the account.

As is shown in the diagram below:

Admins can manage users through the admin interface, where they can view user details, change roles, assign access groups, and deactivate or delete accounts. However, admins cannot edit personal details such as names and affiliated organisations; users must update these themselves through their account settings. Once registered, username, email and user ID cannot be changed.

Super Admin Managing Users

Normal admins cannot assign the super admin role to other users. Only super admins can do this, to prevent privilege escalation. Additionally, super admins can edit the user details while normal admins cannot. Use this functionality with caution.

Local Login and Tokens​

Cafe Variome V4 uses JSON Web Tokens (JWT) for authentication, as the backend is designed to be stateless. The login flow is as follows:

Cafe Variome V4 uses two tokens for authentication:

  • Access Token: A short-lived token (default 15 minutes) used to authenticate API requests. It's returned to the frontend in the response body after a successful login. The frontend stores it in memory and includes it in the Authorization header of subsequent API requests.
  • Refresh Token: A long-lived token (default 24 hours) used to obtain new access tokens without requiring the user to log in again. It's returned to the frontend in an HTTP-only secure cookie after a successful login. This cookie is scoped to only the refresh endpoint, and is not accessible to JavaScript for security reasons. When the access token is about to expire, the frontend sends a request to the refresh endpoint, which verifies the refresh token from the cookie and issues a new access token.

Multi-Factor Authentication (MFA)​

Email-based MFA

With email service configured, Cafe Variome V4 in theory can support email-based MFA by sending a one-time code to the user's email address during login. This feature is currently on the roadmap, but not yet implemented.

Cafe Variome V4 supports optional multi-factor authentication (MFA) using Time-based One-Time Passwords (TOTP). If enabled, it requires KMS service to support TOTP secret encryption, or when the KMS service does not support TOTP natively, it uses KMS to store the TOTP secrets, but processes the TOTP codes locally. The MFA flow is as follows (assuming KMS handles TOTP natively, like Vault by HashiCorp with TOTP engine enabled):

Password Reset​

Email Service Required

In order to use the password reset functionality, an email service must be configured in Cafe Variome V4. Without an email service, the password reset button will be disabled, and an admin must manually reset the user's password through the admin interface.

In case a user forgets their password, they can initiate a password reset process through the "Forgot Password" link on the login page. The backend will send a password reset email with a unique, time-limited token to the user's registered email address. By following the link, the user can set a new password. The password reset flow is as follows: