Merge branch 'feature/hub-1.4.0-features'

Author: SailReal

source/conf.py

@@ -129,10 +129,14 @@
      "hub/setup/billing": "/hub/license",
      "hub/setup/keycloak-administration": "/hub/user-group-management",
      "hub/setup": "/hub/deployment",
-     "hub/access-vault/unlocking-a-vault/4.-vault-unlocked": "/hub/access-vault/unlocking-a-vault/vault-unlocked",
-     "hub/access-vault/unlocking-a-vault/3.-add-device": "/hub/access-vault/unlocking-a-vault/add-device",
-     "hub/access-vault/unlocking-a-vault/2.-authenticate": "/hub/access-vault/unlocking-a-vault/authenticate",
-     "hub/access-vault/unlocking-a-vault/1.-click-unlock": "/hub/access-vault/unlocking-a-vault/click-unlock",
+     "hub/access-vault/unlocking-a-vault/4.-vault-unlocked": "/hub/access-vault/#vault-unlocked",
+     "hub/access-vault/unlocking-a-vault/3.-add-device": "/hub/access-vault/#register-device",
+     "hub/access-vault/unlocking-a-vault/2.-authenticate": "/hub/access-vault/#authenticate",
+     "hub/access-vault/unlocking-a-vault/1.-click-unlock": "/hub/access-vault/#click-unlock",
+     "hub/license": "/hub/admin/license",
+     "hub/license/#what-is-a-seat": "/hub/admin/#what-is-a-seat",
+     "hub/license/#community-license": "/hub/admin/#community-license",
+     "hub/license/#updating-your-license": "/hub/admin/#updating-your-license",
      "desktop/vault-mounting": "/desktop/volume-type"
 }
 

source/hub/admin.rst

@@ -0,0 +1,162 @@
+.. _hub/admin:
+
+Admin
+=====
+
+.. _hub/admin/license:
+
+License
+-------
+
+Every Cryptomator Hub instance requires a license.
+The license is bound to the instance and cannot be transferred to another instance.
+Every license has a number of seats and a validity period.
+As an Hub administrator, you can view license information in the administration area.
+
+.. image:: ../img/hub/admin-area-license.png
+    :alt: Administration area
+
+.. _hub/admin/license/seat:
+
+What is a Seat?
+^^^^^^^^^^^^^^^
+
+A regular license contains a fixed number of *seats*.
+A *seat* is taken for every user, which is assigned to at least one, not-archived vault.
+Note that:
+
+* If a user is not assigned to any vault, it *does not occupy* a seat.
+* If a user is assigned to multiple vaults, it only *occupies one* seat.
+* If :ref:`a user is created or imported to Hub <hub/user-group-management>`, it does not occupy a seat.
+
+.. note:: Enterprise licenses can have an unlimited number of seats. Visit `cryptomator.org <https://cryptomator.org/hub/>`_ for more information.
+
+.. _hub/admin/license/community-license:
+
+Community License
+^^^^^^^^^^^^^^^^^
+
+When you deploy Cryptomator Hub by yourself, it comes with a community license with life-long validity and 5 seats.
+
+.. _hub/admin/license/buy-license:
+
+Updating your License
+^^^^^^^^^^^^^^^^^^^^^
+
+If the community license is not sufficient for your needs, you can upgrade it to a paid license.
+You can also upgrade an already existing, paid license.
+To do so, click on the button in the lower right corner of the administration area.
+It will redirect you to the Cryptomator Hub license store.
+After the purchase, you will be automatically redirected back to your Hub instance.
+
+.. _hub/admin/audit-logs:
+
+Audit Logs
+----------
+
+The Audit Logs provide an overview of security-related events within Cryptomator Hub.
+These logs allow administrators to track important account and vault-related actions.
+
+.. note::
+    Audit Logs are not available with a Community License.
+
+Event Types
+^^^^^^^^^^^
+
+The following events are logged:
+
+Device
+"""""""
+
+- **Register Device** - A user :ref:`registered a new device <hub/access-vault/unlocking-a-vault/add-device>`. This can be e.g. a Cryptomator app (desktop/mobile) to unlock a vault or a web browser to access Cryptomator Hub.
+- **Remove Device** – A user :ref:`removed a device <hub/your-account/profile/authorized-devices>`.
+
+Web of Trust
+""""""""""""
+
+- **Signed Identity** – A user :ref:`signed the identity of another user <hub/vault-management/wot>`.
+- **Update Wot Setting** – A user updated :ref:`Web-of-Trust settings<hub/vault-management/wot>`, e.g. the ``wot_max_depth``.
+
+Vault
+""""""
+
+- **Add Vault Member** – A vault owner :ref:`added a member to a vault <hub/vault-management/add-user>`. This only adds the member but does not derive the vault key for the new member.
+- **Create Vault** – A user :ref:`created a vault <hub/vault-management/create-vault>`.
+- **Grant Vault Access** – A user :ref:`derived the vault key for the new member <hub/vault-management/updating-permission>`.
+- **Retrieve Vault Key** – A user retrieved a vault key. This happens when a user :ref:`unlocks a vault <hub/access-vault/unlocking-a-vault>` but also e.g. when a owner manages the vault. The IP address and device information are optional for legacy reasons.
+- **Remove Vault Member** – A vault owner removed a member from a vault.
+- **Update Vault Member** – A vault owner :ref:`changed a member’s role <hub/vault-management/change-ownership>` (owner or user).
+- **Update Vault** – A vault owner :ref:`updated the vault metadata <hub/vault-management/edit-vault-metadata>`. This includes the vault name or description.
+
+Account
+""""""""
+
+- **Account Key Changed** – A user :ref:`re-generated the account key <hub/your-account/profile/regenerate-account-key>`. This also logs ``User Keys Change`` because changing the account key also changes parts of the user keys.
+- **Reset User Account** – A user :ref:`resetted it's account <hub/your-account/reset-account>`.
+- **User Keys Change** – A user changed it's keys. This happens when e.g. the user :ref:`finished the account setup <hub/your-account/setup>` or when the ``Account Key Changed``.
+
+Legacy
+""""""
+
+- **Claim Vault Ownership** – A user claimed vault ownership. This event is logged when a vault created with hub pre 1.3.0 is claimed by the vault creator using the `Vault Admin Password`.
+
+.. _hub/admin/audit-logs/table-view:
+
+Audit Log Table View
+^^^^^^^^^^^^^^^^^^^^
+
+The logs are displayed in a structured table containing the following columns:
+
+- **Timestamp** – The exact time of the event.
+- **Event** – The type of event that occurred.
+- **Details** – Additional information about the event.
+
+.. image:: ../img/hub/auditlogs-overview.png
+    :alt: Audit Logs Table View
+
+.. _hub/admin/audit-logs/filters:
+
+Filtering Audit Logs
+^^^^^^^^^^^^^^^^^^^^
+
+To refine the displayed logs, a filtering function is available:
+
+.. image:: ../img/hub/auditlogs-filter.png
+    :alt: Audit Log Filtering Options
+
+- **Date Range Filter**: Allows filtering logs between two specific dates.
+- **Event Type Filter**: A multi-select dropdown enables filtering by event type.
+
+.. image:: ../img/hub/auditlogs-filter-events.png
+    :alt: Audit Log Filtering Options
+
+.. _hub/admin/wot:
+
+Web of Trust
+------------
+
+The Web of Trust (WoT) feature in Cryptomator Hub helps users verify each other's identity by signing the :ref:`User Key Pair <security/hub/keys/user-keys>` with their private keys using ECDSA.
+First, the trusting user needs to verify the trustee by entering the first characters of the trustee's public key fingerprint. Once signed, the proof is uploaded to Hub, where others can check its authenticity.
+
+WoT also supports transitive trust, meaning if Alice trusts Bob, and Bob trusts Charlie, then Alice implicitly trusts Charlie. This forms a trust chain, allowing users to establish indirect trust relationships.
+
+.. image:: ../img/hub/wot-admin.png
+    :alt: Audit Log Filtering Options
+
+**In the administration area, administrators can configure the following trust settings:**
+
+The maximum depth of such chains can be configured using the **Maximum WoT Depth** property:
+
+* The default value is 3 ("Great-Grandchild")
+* The maximum value is 9
+* The minimum value, 0, means no trust chain is allowed, only direct trust relationships are considered.
+
+With the **Fingerprint Verification Preciseness** property, the minimum length of the entered public key fingerprint can be configured:
+
+* The default value is 2
+* The minimum value, 0, means the fingerprint of the trustee is fully shown without any input needed.
+
+.. note::
+
+    If a user resets their account, their :ref:`User Key Pair <security/hub/keys/user-keys>` is regenerated, invalidating all previously established trust relationships regarding this user.  
+    Additionally, any existing trust chains that included the user will be broken, requiring re-verification to restore trust.

source/hub/introduction.rst

@@ -21,7 +21,7 @@ If you are…
 …an **administrator**:
 
 * :ref:`User & Group management <hub/user-group-management>` - how to manage users and groups.
-* :ref:`License <hub/license>` - how to manage your Hub license.
+* :ref:`License <hub/admin/license>` - how to manage your Hub license.
 * :ref:`Deployment <hub/deployment>` - how to deploy Cryptomator Hub.
 
 …a **user**:

source/hub/license.rst

@@ -40,3 +40,36 @@ A good step-by-step guide for connecting Microsoft Entra with OpenID Connect can
 
 .. warning::
     Regardless of your choice, your Keycloak instance always contains two local users: ``admin`` and ``syncer``. **Do not edit or delete them!** The first one is for administration tasks and the second one is used to synchronize users and groups between Keycloak and Hub.
+
+
+.. _hub/user-group-management/roles:
+
+Roles
+-------------
+
+There are four different roles in Cryptomator Hub:
+
+* **user**: A user can open vaults and manage their own account.
+* **admin**: An admin manages the Keycloak realm, can see the audit log, and can create vaults.
+* **create-vault**: Only users with this role can create vaults. The role is inherited by the `admin` role.
+
+The ``user``, ``admin``, and ``create-vault`` roles are assigned to users or groups via the Keycloak admin console by an existing user with the ``admin`` role.
+
+.. _hub/user-group-management/roles/create-vault:
+
+Create Vault Role
+^^^^^^^^^^^^^^^^^
+
+By default, this role is only assigned to the ``admin`` role. This means that only users with the ``admin`` role can create vaults. If you want to allow other users to create vaults, you can assign the ``create-vault`` role to them directly or via a group.
+
+If you want that all users can create vaults, assigning the ``create-vault`` role as transient role to the ``user`` role. This way, every user will have the ``create-vault`` role as well.
+
+To allow all users vault creation, assign ``create-vault`` as a transient role to the ``user`` role:
+
+1. Open the Keycloak admin console.
+2. Select ``Realm roles``.
+3. Select the ``user`` role.
+4. Select ``Assign role``.
+5. Select the ``create-vault`` role.
+6. Apply with ``Assign``.
+

source/hub/user-group-management.rst

@@ -34,6 +34,9 @@ Alternatively, you can also access the list by clicking on the ``Vaults`` tab in
 Create a Vault
 --------------
 
+.. note::
+    Creating vaults require the ``create-vault`` role. :ref:`Here <hub/user-group-management/roles>` you can read more about roles.
+
 To create a vault in Hub, navigate to the vault list and click on the ``Create Vault`` button in the top right corner.
 Every vault has a name and optionally a description.
 Fill out the form and continue the process by clicking the ``Next`` button in the right corner.
@@ -165,6 +168,46 @@ To archive the vault, click on the ``Archive Vault`` button in the :ref:`vault d
 
 You can unarchive it by clicking on the ``Owned by me`` tab in the navigation bar, select the vault and clicking on the ``Reactive Vault`` button.
 
+.. _hub/vault-management/wot:
+
+Web of Trust
+^^^^^^^^^^^^
+
+Cryptomator Hub uses a Web of Trust (WoT) to verify the identity of users during vault sharing.
+
+The WoT state of a user is displayed in the vault details page. The state can be one of the following:
+
+* **Unverified**: There is no turst chain between you and the specific user. Indicated with a red shield. You can change this by verifying the user.
+* **Verified**: There is a trust chain between you and the specific user. Indicated with a green shield. You or a user you trust has verified the user.
+
+To verify ``alice``, click on the red shield icon and select ``Check Idenditiy...``
+
+.. image:: ../img/hub/wot-carol-unverified.png
+    :alt: Carol is unverified regarding its Web of Trust state
+    :width: 920px
+
+While verifiying a user, you need to enter the first characters of the user's public key fingerprint. This fingerprint is displayed in user coresponding user profile page.
+
+.. image:: ../img/hub/wot-carol-verify.png
+    :alt: Verify Alice regarding its Web of Trust state
+    :width: 920px
+
+``alice`` is now verified
+
+.. image:: ../img/hub/wot-carol-verified.png
+    :alt: Alice is verified regarding its Web of Trust state
+    :width: 920px
+
+The verification process is logged in the audit log with event type ``Signed Identity``
+
+.. image:: ../img/hub/wot-audit-log.png
+    :alt: WAudit log
+    :width: 920px
+
+``signature still valid`` means that the ``identiy`` has still the same key. If the user account gets reset after verification, this message changes to ``was valid; signed key changed by now`` and the user needs to get verified again.
+
+You can read more details about Web of Trust and how to configure its settings in the :ref:`Admin section of Hub <hub/admin/wot>`.
+
 .. _hub/vault-management/import-vault:
 
 Import a Vault
@@ -176,4 +219,4 @@ For a successful import, the :ref:`recovery key<desktop/password-and-recovery-ke
 The import is done via the Hub vault recovery feature.
 Follow the :ref:`vault online recovery guide <hub/vault-recovery/online-recovery>` and use the recovery key of the password-based vault in the process.
 Don't forget to replace the vault config file ``vault.cryptomator`` at the vault storage location at the end.
-Finally, to ensure that the vault cannot be unlocked with its old password anymore, remove the file ``masterkey.cryptomator`` and all backup files ( ending with ``.bkup``).
+Finally, to ensure that the vault cannot be unlocked with its old password anymore, remove the file ``masterkey.cryptomator`` and all backup files (ending with ``.bkup``).