Authentication
- Code: ACC-AUT
- Module: Account
- Type: Configuration
1. Overview
Authentication is the entry point to the Tenant Backoffice. It ensures that only legitimate account owners can enter, keeps access secure while the app is in use, and helps users recover their own access when they forget their password. Once inside, users can only use the app according to their role. Accounts are created by an admin through Users, so there is no self-registration.
Expected outcome: the app can only be used by the rightful account owner, users can recover their own access when they forget their password without waiting for an admin, and users whose access or login has ended are taken straight back to the login page.
2. Problem
Without a clear authentication flow, the rules for signing in, signing out, and recovering an account are scattered across other features and answered with each person’s own assumptions. As a result:
- Users who forget their password have to ask an admin to reset their account.
- The rules for accounts that are unverified, inactive, or whose login was revoked have no single reference.
- Other features (My Account, Linked Devices, Users) refer to a login flow that is not written down anywhere.
3. Goals & Non-goals
3.1 Goals
- Only active users can log in with email and password, then are taken straight to the page they wanted to open.
- Users who forget their password can reset it themselves through a link sent to their email, without admin help.
- New users set their own password through a link in an email, and an admin can resend the link if it expires or does not arrive.
- Users stay logged in while actively using the app, and are returned to the login page after 7 days without activity or when their login is revoked from Linked Devices.
3.2 Non-goals
- Self-registration; accounts are created only by an admin through Users.
- Two-factor authentication (OTP) and third-party login (SSO).
- Managing roles and access rights; those are set in Roles & Permissions.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Authentication across the whole app, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rule here prevails.
- BR-01 Users log in with their email and password. If either is wrong, the message shown is always the same, so the user cannot tell which one is wrong. A password shorter than 8 characters is rejected right away, before it is matched. An account that has not set a password also cannot log in, with the same message (BR-14). 🚧 Not yet: BE
- BR-02 An inactive account cannot log in or reset its password. When trying to log in, the user sees a message to contact the administrator. If an account is deactivated while the user is logged in, the user is not logged out automatically, but every further data request is rejected. 🚧 Not yet: BE
- BR-03 After a successful login, the user is taken to the page they originally wanted to open, as long as that page is inside this app. Otherwise the user is taken to the home page.
- BR-04 The new password must be at least 8 characters, contain letters, numbers, and symbols, and match its confirmation. These rules are checked when the password is saved; before that, the form only ensures all fields are filled in.
- BR-05 A user who forgets their password requests a reset link by email. The message shown is always the same, whether or not the email is registered, so others cannot guess which emails are registered. An account that has not set a password does not receive a reset link (BR-14). The link is valid for 60 minutes and can only be used once; a new link replaces the old one. The link is checked before the form is shown. 🚧 Not yet: BE
- BR-06 After a password is reset or changed, or after a changed login email is verified, the account owner is automatically logged out of all devices, including the one in use, and their device notifications are removed. The user then logs in again with the new password or email. 🚧 Not yet: FE + BE
- BR-07 When an admin creates a new account in Users, the admin does not enter or see its password, and the system does not generate or send one. The new user receives an email with a link to set their own password. The link is valid for 60 minutes, can only be used once, and is checked before the form is shown. If a new link is sent, the previous one stops working. 🚧 Not yet: FE + BE
- BR-08 Once the new user sets a password according to BR-04, the link can no longer be used, the account’s email is automatically treated as verified, and the user is sent to the login page. Setting the password is recorded in the activity log. 🚧 Not yet: FE + BE
- BR-09 An account’s email must be proven to belong to its user. A new account is automatically verified once it sets its password (BR-08). A changed login email is always verified separately: the user opens the verification link sent to the new email; the link is valid for 60 minutes and single-use. The same applies to older unverified accounts.
- BR-10 A user who already has a password but whose email is not yet verified (for example after changing email) can still log in, but cannot use the app’s features. All they can do is view their own data in My Account. A banner at the top of the app reminds the user and provides a button to resend the verification link.
- BR-11 While the user keeps using the app, their login is renewed automatically in the background, so they do not need to log in again. After 7 days without activity, or if the login is revoked from Linked Devices, the user is returned to the login page.
- BR-12 A user who is already logged in is sent to the home page when opening the login, forgot password, or reset password pages. The email verification and new-account set-password pages are the exception, because the account owner may still be logged in when opening the link. A user who is not logged in is always sent to the login page. 🚧 Not yet: FE
- BR-13 Every login and logout is recorded in the activity log, including who did it and when, so the account’s access history can be traced.
- BR-14 An account that has not set a password is not yet active: its owner cannot log in, cannot request a password reset, and cannot do anything in the app. The only way forward is to open the set-password link from the email (BR-07). 🚧 Not yet: BE
- BR-16 When a user logs in from a device not yet recorded in their Linked Devices, the system sends that user a notification with the device name, approximate location, and login time, so a login that is not theirs can be spotted quickly. The notification does not appear as a toast or device notification on the device that just logged in. The first login of an account that has no recorded device does not trigger a notification. 🚧 Not yet: BE
- BR-15 If the set-password link has expired or the email did not arrive, an admin resends it from the user detail in Users. The new link is valid for 60 minutes and replaces all previous links. The resend button is only available while the account has not set a password, and every resend is recorded in the activity log. 🚧 Not yet: FE + BE
5. Flow
5.1 Main Flowchart
- Account Created by Admin — An admin creates a new account in Users without entering a password. The system sends an email with a set-password link to that account’s address. Until the password is set, the account cannot be used at all (BR-07, BR-14). 🚧 Not yet: FE + BE
- Set Password for New Account — The new user opens the link from the email. The link is checked, its owner’s email is shown, then the user fills in a password and its confirmation. After success, the account’s email is verified and the user is sent to the login page (BR-04, BR-08). 🚧 Not yet: FE + BE
- Admin Resends Link — If the link expired or the email did not arrive, the admin presses Resend Link in the user detail. A new link is sent to the same email and the old link stops working (BR-15). 🚧 Not yet: FE + BE
- Login — The user fills in email and password. On success, the user is taken to the page they wanted to open or to the home page. If the device is new, the account owner is notified (BR-01, BR-03, BR-16). 🚧 Not yet: BE
- Use the App — Every access is checked: the login is still valid, the account is still active, the email is verified, and the role allows the page being opened. If the email is not verified, the user can only view My Account and the verification banner is shown (BR-10). Any other access outside the role’s permissions shows the access denied page.
- Request Reset Link — The user fills in their email, then a reset link is sent if the email is registered, the account is active, and its password has been set before (BR-02, BR-05, BR-14). 🚧 Not yet: BE
- Reset Password — The link is checked, its owner’s email is shown, then the user fills in the new password and its confirmation. After success, the user is logged out of all devices and returns to login (BR-04, BR-06).
- Verify Email — The user opens the verification link from the email to prove a changed login email or the email of an older unverified account, then logs in. A new account does not go through this step because it is already verified when it sets its password (BR-09).
- Back to Login — When a login expires or is revoked, the app logs the user out automatically and remembers the destination page (BR-11).
- Logout — The user confirms logging out; the login on that device ends and the user returns to the login page (BR-13).
6. Document Structure
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Text | Yes | — | Valid format; also the login identity (BR-01) | |
| Password | Text | Yes | — | Matched against the account’s password (BR-01) |
| New Password | Text | Yes, when resetting the password or setting the password of a new account | — | At least 8 characters with letters, numbers, and symbols; checked on save (BR-04) |
| Confirm New Password | Text | Yes, when resetting the password or setting the password of a new account | — | Must match New Password exactly (BR-04) |
| Device ID | Text | — | Generated automatically in the browser on first use | Marks the device used to log in (BR-11) |
| Destination | Text | No | Home page | Only addresses inside the app are followed (BR-03) |
7. UI Structure
This section defines how Authentication is displayed and operated: form controls and their option sources. It only governs presentation and interaction; the rules for content and values still follow Document Structure.
7.1 Form
Login
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Text Input | — | — | |
| Password | Text Input (can be revealed) | — | — |
Actions: Sign In, and a Forgot password link.
Forgot Password
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Text Input | — | — |
Actions: Send Link, and a Back to Sign In link.
Reset Password
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Text | — | Shows the link owner’s email above the form; cannot be edited | |
| New Password | Text Input (can be revealed) | — | Shown after the link is confirmed valid |
| Confirm New Password | Text Input (can be revealed) | — | Must match New Password |
Actions: Save Password.
Set Password for New Account 🚧 Not yet: FE + BE
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Text | — | Shows the account owner’s email above the form; cannot be edited | |
| New Password | Text Input (can be revealed) | — | Shown after the link is confirmed valid |
| Confirm New Password | Text Input (can be revealed) | — | Must match New Password |
Actions: Save Password.
8. User Stories
US-01 - Login
As a user, I want to log in with my email and password, so I can use the app according to my role.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | Email and password are required; the form is not submitted if either is empty. |
| AC-01.2 | Wrong email or password — the same message appears on the email field and as a toast, without revealing the cause (BR-01). |
| AC-01.3 | An account that has not set a password tries to log in — rejected with the same message as a wrong email or password. This account also cannot do anything in the app until the password is set (BR-01, BR-14). 🚧 Not yet: BE |
| AC-01.4 | Inactive account — login is rejected with a message to contact the administrator (BR-02). |
| AC-01.5 | Account is deactivated while the user is logged in — the user is not logged out automatically, but the next data request is rejected with an inactive-account message (BR-02). |
| AC-01.6 | Login succeeds — the user is taken to the page they wanted to open if it is inside the app, otherwise to the home page (BR-03). |
| AC-01.7 | A logged-in user opens the login, forgot password, or reset password page — sent to the home page (BR-12). |
| AC-01.8 | A user who is not logged in opens a page inside the app — sent to login, and the destination page is remembered (BR-03, BR-12). |
| AC-01.9 | A user opens a page outside their role’s permissions — the access denied page is shown, and the login stays valid. |
| AC-01.10 | A successful login from a device not recorded in Linked Devices — the account owner receives a notification with the device name, approximate location, and login time; it does not appear as a toast or device notification on the device that just logged in (BR-16). 🚧 Not yet: BE |
| AC-01.11 | The first login of an account with no recorded device — no notification (BR-16). 🚧 Not yet: BE |
| AC-01.12 | Logging in again from the same device after logout or revocation — Needs confirmation: whether it counts as a new device, since it is no longer in the list. |
US-02 - Forgot and reset password
As a user, I want to reset my password myself, so I can log in again without admin help.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | After the email is sent, the same message appears for registered and unregistered emails, then the user returns to the login page (BR-05). |
| AC-02.2 | An inactive account requests a reset link — the message shown is the same as for other accounts, but no link is sent; an old link is rejected as invalid (BR-02, BR-05). 🚧 Not yet: BE |
| AC-02.3 | Opening the link checks it first; while it is checked, a verifying status is shown, then the link owner’s email is shown (BR-05). |
| AC-02.4 | Link expired, invalid, or already used — the page shows an invalid-link message with a way back to login (BR-05). |
| AC-02.5 | New password and confirmation are required; the password rules and the match are checked on save, with errors on the related fields (BR-04). |
| AC-02.6 | After success, the user is logged out of all devices and returns to the login page (BR-06). |
| AC-02.8 | The user requests a reset link again — a new link is sent and the previous one stops working (BR-05). |
| AC-02.7 | An account that has not set a password requests a reset link — the same message is shown as for other accounts, but no link is sent; the user must set the password through the original link in the email (BR-05, BR-14). 🚧 Not yet: BE |
US-03 - Set the password of a new account
As a new user, I want to set my own password through a link in an email, so that no password is sent or known to anyone else.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | An admin saves a new user — an email with a set-password link is sent to the account’s address, with no password in it (BR-07). 🚧 Not yet: FE + BE |
| AC-03.2 | Opening the link checks it first; while it is checked, a verifying status is shown, then the account owner’s email is shown above the form (BR-07). 🚧 Not yet: FE + BE |
| AC-03.3 | Link expired, invalid, or already used — the page shows an invalid-link message with a way back to login (BR-07). The user contacts an admin to request a new link (BR-15). 🚧 Not yet: FE + BE |
| AC-03.4 | New password and confirmation are required; the password rules and the match are checked on save, with errors on the related fields (BR-04). 🚧 Not yet: FE + BE |
| AC-03.5 | After success, a success toast appears, the account’s email is verified, the user is sent to the login page, and setting the password is recorded in the activity log (BR-08). 🚧 Not yet: FE + BE |
| AC-03.6 | A logged-in user opens the link — the page is still shown, not redirected to the home page (BR-12). 🚧 Not yet: FE |
US-04 - Resend set-password link
As an admin, I want to resend the set-password link to a new user, so the user can still activate their account when the link expires or the email does not arrive.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | The Resend Link button appears in the user detail only while the user has not set a password (BR-15). 🚧 Not yet: FE + BE |
| AC-04.2 | After it is pressed, a new link is sent to the same email and the previous link stops working immediately (BR-07, BR-15). 🚧 Not yet: FE + BE |
| AC-04.3 | The resend is recorded in the activity log (BR-15). 🚧 Not yet: FE + BE |
| AC-04.4 | A user who has already set a password — the button is not available (BR-15). 🚧 Not yet: FE + BE |
US-05 - Verify email
As a user, I want to verify my email through a link when my login email is changed or my account is not yet verified, so my account can be used and stays secure.
| ID | Acceptance criteria |
|---|---|
| AC-05.1 | A user who already has a password but an unverified email logs in — successfully, but can only view their own data in My Account and other features are rejected (BR-10). Needs confirmation: whether after an email change the user should also be fully blocked, like an account that has not set a password. |
| AC-05.2 | A banner at the top of the app explains this and provides a button to resend the verification link. The button shows a sending state, then a sent and disabled state until the page is reloaded; a success or failure toast appears (BR-10). |
| AC-05.3 | Opening the verification link shows a processing status; after success, a success toast appears and the user is sent to login (BR-09). |
| AC-05.4 | Link expired, invalid, or the email was already verified — the page shows a failed status and only offers a way back to login, so the user must log in first to use the resend button in the banner (BR-09, BR-10). |
| AC-05.5 | The verification link for a changed login email uses the same page and can still be opened by a logged-in user (BR-12); after success the user is logged out of all devices and logs in with the new email (BR-06). |
US-06 - Login expires
As a user, I want to be logged out clearly when my login is no longer valid, so I am not confused by pages that fail to load.
| ID | Acceptance criteria |
|---|---|
| AC-06.1 | The user keeps using the app — their login is renewed automatically without logging in again (BR-11). |
| AC-06.2 | No activity for 7 days, or the login is revoked from Linked Devices — the app logs the user out automatically and takes them to login (BR-11). |
US-07 - Logout
As a user, I want to log out of the app, so my account stays safe on a shared device.
| ID | Acceptance criteria |
|---|---|
| AC-07.1 | Choosing Logout opens a confirmation dialog first. |
| AC-07.2 | After confirmation, the login on that device ends and the user returns to the login page; other devices are unaffected. |
| AC-07.3 | Logout is recorded in the activity log (BR-13). |
9. User Scenarios
| Role | Scenario |
|---|---|
| Admin | Creates a new account in Users, then the new user receives an email with a set-password link |
| New user | Opens the link from the email, sets their own password, then logs in for the first time |
| Admin | A new user’s link expired or the email did not arrive; the admin presses Resend Link in the user detail |
| User | Logs in at the start of work and logs out at the end from a shared device |
| User | Logs in from a new laptop, then receives a notification on another device and checks their devices in Linked Devices |
| User | Forgets their password, requests a reset link, then logs in with the new password |
| User | Opens a saved link when the login has already expired, logs in again, and lands directly on the target page |
| User | Changes their password from My Account, then logs in again on all devices |
| User | Changes their login email, verifies it through a link, then logs in with the new email |
10. Permissions & Actions
This feature has no permissions; all Authentication features are available to all users.
11. Notifications
| Event | Recipient | Title | Body | Destination |
|---|---|---|---|---|
| Login from a new device (BR-16) | Account owner | New device login | Your account was logged in from {device name} in {city, country} on {login time}. If this was not you, revoke this device in Linked Devices. | /account/linked-devices 🚧 Not yet: BE |
12. Dependencies
Related PRDs
- Users (Settings) — admin creates accounts, sets active status (an inactive account is rejected at login, when accessing data, and when resetting its password), and triggers the set-password email for new accounts (BR-07). The Resend Link button is in the user detail (BR-15).
- My Account — changing the password (BR-06) and the login email (BR-09) follow the rules here; a user whose email is not yet verified can only view this page (BR-10).
- Linked Devices — revokes logins; a revoked login returns to the login page (BR-11). Its device list is used to recognize a new device (BR-16).
- Roles & Permissions — determines which pages can be opened after login.
- Activity Logs — records login and logout (BR-13), setting the password of a new account (BR-08), and resending the link (BR-15).
Effects on other modules
- A login from a new device sends a notification to the account owner through Notifications (BR-16).
- Resetting or changing the password, and verifying a changed login email, remove the user’s device notifications (BR-06). Notifications registers them again at the user’s next login, if browser notification permission is still granted.