.. include:: ../variables.rst .. _authentication: Authentication ============== |APPNAME| controls access through three layers: * **Users** --- the individual accounts that log in. * **Roles** --- the permission sets that say what a user can do. * **Auditor Groups** --- optional groupings that let you report on observations by the team of auditors that recorded them. Plus a security add-on that applies across all three: * **Two-Factor Authentication** --- a second sign-in challenge for users you want to protect more strongly. .. include:: ../_password.requirements.txt Passwords are never stored in a form anyone can read. For details on how they are protected, and for the full set of security features (two-factor authentication, failed-login auto-blocking, the blocked IPs list, and the threat map), see :ref:`security`. .. _users: Users ----- To open the Users list, go to :blue:`Account` | :blue:`Users` | :blue:`User Accounts`. .. figure:: /images/lightmode/users-list.png :align: center |br| Each row is one user account with the columns you would expect (name, username, email, role, status, last sign-in). Row Action Menu ^^^^^^^^^^^^^^^ Click the three-dot icon at the end of any row: * ``Edit`` --- opens the :ref:`user.editor`. * ``View Logins`` --- opens the user's sign-in history. * ``Clinical Ladder`` --- opens a summary of the audits the user has recorded. * ``Reset Password`` --- sends a password-reset email to the user's address on file. * ``Logout`` --- ends the user's active sessions across every device immediately. * ``Delete`` --- permanently removes the user account after a confirmation prompt. .. _user.editor: User Editor ^^^^^^^^^^^ Click a user (or pick ``Edit`` from the row menu) to open the editor. Information is grouped into tabs. General """"""" .. figure:: /images/lightmode/user-detail-general.png :align: center |br| Basic profile information --- name, title, email address, role, facility and unit assignment. Login """"" .. figure:: /images/lightmode/user-detail-login.png :align: center |br| Sign-in settings --- username, password reset, and the ``Two-Factor Authentication`` toggle (see :ref:`two.factor`). Certification """"""""""""" Records the user's certification as an auditor: the certification date, expiry, and any renewal notes. Reports and the :ref:`Hand Hygiene Sessions list` read this information when reporting on certified vs. non-certified observations. Kiosk """"" Configures the user as a kiosk-only account that can show the dashboard on a shared screen but cannot otherwise change data. Dates """"" Account start and end dates, used together with the role's ``Auto Expire`` setting to automatically disable users whose term has ended. .. _roles: Roles ----- |APPNAME| controls what a user can do through **Roles**. Every user is assigned exactly one role; the role's permissions and unit assignments decide the pages, actions, and units the user can reach. Typical out-of-the-box roles: * ``HH Administrator`` --- full access to hand-hygiene configuration, reporting, and auditing. * ``HH Observer`` --- can record audits but cannot change configuration. You can define as many additional roles as you need. To open the Roles list, go to :blue:`Account` | :blue:`Users` | :blue:`Roles`. .. figure:: /images/lightmode/roles-list.png :align: center |br| Row Action Menu ^^^^^^^^^^^^^^^ Click the three-dot icon at the end of any row: * ``Edit`` --- opens the :ref:`role.editor`. * ``Delete`` --- permanently removes the role after a confirmation prompt. A role with users still assigned to it cannot be deleted until those users are reassigned. .. _role.editor: Role Editor ^^^^^^^^^^^ The role editor is organized into six tabs. General """"""" .. figure:: /images/lightmode/role-detail-general.png :align: center |br| * ``Active Role`` --- toggle the whole role on or off. Disabling a role prevents every user in it from signing in. Useful for seasonal contractor accounts. * ``Role Type`` --- ``Standard`` (recommended for auditor-only accounts) or ``Administrator``. Administrator roles can reach configuration pages that Standard roles cannot. * ``Auto Expire Accounts`` --- automatically disables users in this role once the expiry date on their profile passes. * ``Allow Logins`` --- if disabled, nobody in this role can sign in. Used to lock out a role without disabling each user individually. * ``Allow Audit Backdating`` --- lets users in this role enter a previous date when starting an audit in |AUDITSOFTWARE|. .. warning:: Set auditor-only roles to ``Standard``. Standard roles are restricted to the features an auditor actually uses and cannot change configuration. Display / Notifications / Hand Hygiene """""""""""""""""""""""""""""""""""""" Per-role visual preferences, notification preferences, and hand hygiene workflow options. These apply to every user in the role unless overridden in the user's individual profile. Permissions """"""""""" .. figure:: /images/lightmode/role-detail-permissions.png :align: center |br| The permission matrix lists every feature in |APPNAME|. Tick each feature the role should have access to; leave the rest unchecked. Permissions are additive --- if the matrix does not grant access, the role cannot reach that feature. Unit Assignments """""""""""""""" .. figure:: /images/lightmode/role-detail-units.png :align: center |br| Limit a role to specific units. Tick each unit the role is allowed to audit; leave the rest unchecked. A role with no units ticked can audit in every unit (the default); a role with at least one unit ticked is restricted to the ticked set. Click ``Submit`` to save any changes across the tabs, or ``Cancel`` to discard them. .. _auditor.groups: Auditor Groups -------------- Auditor Groups let administrators bundle auditors together so their observations can be reported or charted as a single dataset --- for example *Infection Prevention and Control* auditors vs. *Hand Hygiene Champions*. To open the list, go to :blue:`Account` | :blue:`Users` | :blue:`Users Group`. Creating a Group ^^^^^^^^^^^^^^^^ Click ``Add a User Category`` from the action menu, then: 1. Name the group and give it a description. 2. Toggle ``Active`` on. 3. Tick ``Include in Dashboard`` if you want observations from this group to appear on the dashboard. 4. Save. Users are added to the group from their individual :ref:`User Editor`. Default Group ^^^^^^^^^^^^^ One group can be marked as the *default*. Any new user who isn't explicitly assigned to another group is assigned to the default. |APPNAME| creates and maintains a ``Default User Category`` if none exists. Deleting a Group ^^^^^^^^^^^^^^^^ Disable the group first (untick ``Active``) --- the trash icon is only available on disabled groups. Deleting moves every assigned auditor back into ``Uncategorized``. How Groups Are Used ^^^^^^^^^^^^^^^^^^^ * Reports --- any report definition that scopes by user category. * Dashboard --- the ``Compliance by Group`` widget reads from this list. * Filtering --- the audit-session list filters by auditor group. .. _two.factor: Two-Factor Authentication ------------------------- |APPNAME| supports time-based one-time-password (TOTP) two-factor authentication (2FA) for user accounts. When 2FA is enabled for a user, sign-in requires the account password plus a six-digit code generated by an authenticator app on the user's phone (for example Google Authenticator, Microsoft Authenticator, Authy, or 1Password). .. figure:: /images/two-factor-prompt.png :align: center |br| Enabling 2FA for a User ^^^^^^^^^^^^^^^^^^^^^^^ Administrators turn 2FA on or off from the :ref:`User Editor` ``Login`` tab. With 2FA enabled: * On the user's next sign-in, |APPNAME| shows a setup screen with a QR code. * The user scans the QR code with an authenticator app, which then generates a fresh six-digit code every 30 seconds. * The user enters the current code to confirm the pairing and finish sign-in. Signing In with 2FA ^^^^^^^^^^^^^^^^^^^ After entering your username and password you are taken to the 2FA prompt. Enter the current six-digit code from your authenticator app. If the code matches, sign-in completes and you are taken to the dashboard. Lost Device / Reset ^^^^^^^^^^^^^^^^^^^ If a user loses access to their authenticator (for example when replacing a phone), an administrator can disable 2FA from the user's editor. The next time the user signs in they are prompted to pair a new authenticator. .. _ldap: LDAP / Active Directory ----------------------- LDAP and Active Directory sign-in is available with |APPNAME| |UEDITION| edition for on-premise deployments. Contact |SUPPORTEMAIL| for configuration help.