Merge pull request #152 from nextcloud/files-access-control-docs

Files access control docs

admin_manual/configuration_files/files_access_control.rst

@@ -0,0 +1,73 @@
+====================
+Files Access Control
+====================
+
+Nextcloud's File Access Control app enables administrators to create and
+manage a set of rule groups. Each of the rule groups consists of one or more
+rules. If all rules of a group hold true, the group matches the request and
+access is being denied. The rules criteria range from IP address, to user
+groups, collaborative tags and :ref:`some more <available-rules-label>`.
+
+Denied access
+-------------
+
+If access to a file has been denied for a user, the user can not:
+
+* Create/upload the file
+* Modify the files
+* Delete the file
+* Download the file
+* Syncronise the file with clients, such as the Nextcloud desktop and mobile clients
+
+Examples
+--------
+
+    .. figure:: images/files_access_control_sample_rules.png
+       :alt: Sample rules to block on user group, time and IP base.
+
+The first rule group ``Support only 9-5`` denies any access to files for users
+of the Support user group, between 5pm and 9am.
+
+The second rule group ``Internal testing`` prevents users of the Internal
+testers group to access files from outside of the local network.
+
+Denying access to folders
+-------------------------
+
+The easiest way to block access to a folder, is to use a collaborative tag. As
+mentioned in the :ref:`Available rules <available-rules-label>` section below,
+either the file itself or one of the parents needs to have the given tag
+assigned.
+
+So you just need to assign the tag to the folder or file, and then block the
+tag with a rule group. The check is independent of the user's permissions for
+the tag. Therefor restricted and invisible tags are recommended, otherwise a
+user could remove and reassign the tag.
+
+This example blocks access to any folder with the tag ``Confidential``.
+
+    .. figure:: images/files_access_control_collaborative_tags.png
+       :alt: Deny access based on collaborative tag
+
+.. _available-rules-label:
+
+Available rules
+---------------
+
+All rules can also be inverted (from ``is`` to ``is not``) using the operator
+option.
+
+* **File collaborative tag:** Either the file itself, or any of the file
+  owner's parent folders needs to be tagged with the tag.
+* **File mimetype:** The mimetype of the file, e.g. ``text/plain``
+* **File size:** The size of the file (*Only available on upload*)
+
+* **Request remote address:** An IP range (either v4 or v6) for the accessing user
+* **Request time:** Time span and timezone when the request happens
+* **Request URL:** The URL which requests the file. (*This is the URL the file
+  is served from, not the URL the user is currently looking at.*)
+* **Request user agent:** The user agent of the users browser or client.
+  Nextcloud desktop, Android and iOS clients are available as preconfigured
+  options.
+
+* **User group membership:** Whether the user is a member of the given group.

admin_manual/configuration_files/index.rst

@@ -18,3 +18,4 @@ File Sharing and Management
     files_locking_transactional
     previews_configuration
     file_versioning
+    files_access_control

admin_manual/configuration_server/index.rst

@@ -25,4 +25,4 @@ Nextcloud Server Configuration
    oc_server_tuning
    theming
 
-   .. Intentional disabled antivirus_configuration
+.. Intentional disabled antivirus_configuration

go.php

@@ -9,6 +9,7 @@ $mapping = array(
     'admin-external-storage'  => '/admin_manual/configuration_files/external_storage_configuration_gui.html',
     'admin-sharing-federated' => '/admin_manual/configuration_files/federated_cloud_sharing_configuration.html',
     'admin-sharing'           => '/admin_manual/configuration_files/file_sharing_configuration.html',
+    'admin-files-access-control' => '/admin_manual/configuration_files/files_access_control.html',
     'admin-transactional-locking' => '/admin_manual/configuration_files/files_locking_transactional.html',
     'admin-background-jobs'   => '/admin_manual/configuration_server/background_jobs_configuration.html',
     'admin-config'            => '/admin_manual/configuration_server/config_sample_php_parameters.html',