diff --git a/admin_manual/configuration_server/images/firewall-1.png b/admin_manual/configuration_server/images/firewall-1.png new file mode 100644 index 000000000..9ac6eabd1 Binary files /dev/null and b/admin_manual/configuration_server/images/firewall-1.png differ diff --git a/admin_manual/enterprise_user_management/file_firewall.rst b/admin_manual/enterprise_user_management/file_firewall.rst new file mode 100644 index 000000000..42c905481 --- /dev/null +++ b/admin_manual/enterprise_user_management/file_firewall.rst @@ -0,0 +1,174 @@ +====================== +File Firewall(ES only) +====================== + +The File Firewall GUI enables you to create and manage firewall rule sets from +your ownCloud admin page. The File Firewall gives you finer-grained control of +access and sharing, with rules for allowing or denying access, and restrictions +per group, upload size, client devices, IP address, time of day, and many more +criteria. For additional flexibility the File Firewall also supports regular +expressions. + +Each rule consists of one or more conditions. A request matches a rule if +all conditions evaluate to true. If a request matches at least one of the +defined rules, the request is blocked. + +Administrators are excluded from the firewall when they +access the instance via the WebUI, to allow admins to modify the rules. +Otherwise they could potentially be locked out. Public share links and syncing +via WebDAV are subject to firewall rules for all users all the time. + +Figure 1 shows an empty firewall configuration panel. Set your logging level to +**Failures Only** for debugging, and create a new ruleset by clicking the **Add +Group** button. After setting up your rules you must click the **Save Rules** +button. + +.. figure:: images/firewall-1.png + :alt: Empty File Firewall configuration panel. + + *Figure 1: Empty File Firewall configuration panel* + +Figure 2 shows two rules. The first rule, **No Support outside +office hours**, prevents members of the support group from logging into the +ownCloud Web interface from 5pm-9am. + +The second rule prevents members of the qa-team group from accessing the Web UI +from IP addresses that are outside of the local network. + +.. figure:: images/firewall-2.png + :alt: Two example rules that restrict logins per user group. + + *Figure 2: Two example rules that restrict logins per user group* + +All other users are not affected, and can log in anytime from anywhere. + +Available Conditions +-------------------- + +User Group + The user (is|is not) a member of the selected group. + +User Agent + The User-Agent of the request (matches|does not match) the given string. + +User Device + A shortcut for matching all known (`android`|`ios`|`desktop`) sync clients by + their User Agent string. + +Request Time + The time of the request (has to|must not) in a single range from beginning + time to end time. + +Request URL + The **full page URL** (has to|must not) (match|contain|begin with|end) with a + given string. + +Request Type + The request (is|is not) a (WebDAV|public share link|other) request. + +Request IP Range + The request's ``REMOTE_ADDR`` header (is|is not) matching the given IP range. + +Subnet + The request's ``SERVER_ADDR`` header (is|is not) matching the given IP range. + +File Size Upload + When a file is uploaded the size has to be (less|less or equal|greater|greater + or equal) to the given size. + +File Mimetype Upload + When a file is uploaded the mimetype (is|is not|begins with|does not begin + with|ends with|does not end with) the given string. + +Regular Expression + The File Firewall supports regular expressions, allowing you to create custom + rules using the following conditions: + +* User IP +* Subnet +* User agent +* User group +* Request URL + +You can combine multiple rules into one rule. E.g., if a rule applies to both +the support and the qa-team you could write your rule like this:: + + Regular Expression > `^(support|qa-team)$` > `is` > `User group` + +No Manual Editing +----------------- + +We do not recommend modifying the configuration values directly in your +``config.php``. These use JSON encoding, so the values are difficult to read +and a single typo will break all of your rules. + +Correctly Blocking Access to a Folder +------------------------------------- + +See examples of the correct regexp syntax to use for controlling access to +specific folders at +`Example rule to restrict access to a folder based on +CIDR `_. +It is quite important to note that WebDAV and WebUI require two different URL +matches in 8.2, and are therefore split into 2 rules. + +Custom Configuration for Branded Clients +---------------------------------------- + +If you are using :doc:`branded ownCloud clients <../enterprise_clients/index>`, +you may define ``firewall.branded_clients`` in your ``config.php`` to identify +your branded clients in the firewall **"User Device"** rule. + +The configuration is a ``User-Agent`` => ``Device`` map. ``Device`` must be one +of the following: + +* android +* android_branded +* ios +* ios_branded +* desktop +* desktop_branded + +The ``User-Agent`` is always compared all lowercase. By default the agent is +compared with ``equals``. When a trailing or leading asterisk, ``*``, is found, +the agent is compared with ``starts with`` or ``ends with``. If the agent has +both a leading and a trailing ``*``, the string must appear anywhere. For +technical reasons the ``User-Agent`` string must be at least 4 characters +(including wildcards). (When you build your branded client you have the option +to create a custom User Agent.) + +In this example configuration you need to replace the example User Agent +strings, for example ``'android_branded'``, with your own User Agent strings:: + + // config.php + + 'firewall.branded_clients' => array( + 'my ownbrander android user agent string' => 'android_branded', + 'my ownbrander second android user agent string' => 'android_branded', + 'my ownbrander ios user agent string' => 'ios_branded', + 'my ownbrander second ios user agent string' => 'ios_branded', + 'my ownbrander desktop user agent string' => 'desktop_branded', + 'my ownbrander second desktop user agent string' => 'desktop_branded', + ), + +The Web UI dropdown then expends to the following options: + +* Android Client - always visible +* iOS Client - always visible +* Desktop Client - always visible +* Android Client (Branded) - visible when at least one ``android_branded`` is defined +* iOS Client (Branded) - visible when at least one ``ios_branded`` is defined +* Desktop Client (Branded) - visible when at least one ``desktop_branded`` is defined +* All branded clients - visible when at least one of ``android_branded``, + ``android_branded`` or ``desktop_branded`` is defined +* All non-branded clients - visible when at least one of ``android_branded``, + ``android_branded or ``desktop_branded`` is defined +* Others (Browsers, etc.) - always visible + +Then these options operate this way: + +* The ``* Client`` options only match ``android``, ``ios`` and ``desktop`` respectively. +* The ``* Client (Branded)`` options match the ``*_branded`` agents equivalent. +* ``All branded clients`` matches: ``android_branded``, ``ios_branded`` and + `desktop_branded` +* ``All non-branded clients`` matches: ``android``, ``ios`` and ``desktop`` diff --git a/admin_manual/enterprise_user_management/images/firewall-1.png b/admin_manual/enterprise_user_management/images/firewall-1.png new file mode 100644 index 000000000..a8adabc13 Binary files /dev/null and b/admin_manual/enterprise_user_management/images/firewall-1.png differ diff --git a/admin_manual/enterprise_user_management/images/firewall-2.png b/admin_manual/enterprise_user_management/images/firewall-2.png new file mode 100644 index 000000000..411cdeb02 Binary files /dev/null and b/admin_manual/enterprise_user_management/images/firewall-2.png differ diff --git a/admin_manual/enterprise_user_management/index.rst b/admin_manual/enterprise_user_management/index.rst index 7032ab785..0667730af 100644 --- a/admin_manual/enterprise_user_management/index.rst +++ b/admin_manual/enterprise_user_management/index.rst @@ -5,4 +5,5 @@ User Management (ES only) .. toctree:: :maxdepth: 2 + file_firewall user_auth_shibboleth