Merge pull request #9282 from open-sausages/pulls/4/docs/clarify-basic-auth

DOCS Clarify BasicAuth limitations

docs/en/00_Getting_Started/03_Environment_Management.md

@@ -99,7 +99,7 @@ SilverStripe core environment variables are listed here, though you're free to d
 | `SS_ENVIRONMENT_TYPE`| The environment type: dev, test or live.|
 | `SS_DEFAULT_ADMIN_USERNAME`| The username of the default admin. This is a user with administrative privileges.|
 | `SS_DEFAULT_ADMIN_PASSWORD`| The password of the default admin. This will not be stored in the database.|
-| `SS_USE_BASIC_AUTH`| Protect the site with basic auth (good for test sites).<br/>When using CGI/FastCGI with Apache, you will have to add the `RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]` rewrite rule to your `.htaccess` file|
+| `SS_USE_BASIC_AUTH`| Baseline protection for requests handled by SilverStripe. Usually requires additional security measures for comprehensive protection. See [Environment Types](/developer_guides/debugging/environment_types) for caveats.|
 | `SS_SEND_ALL_EMAILS_TO`| If you define this constant, all emails will be redirected to this address.|
 | `SS_SEND_ALL_EMAILS_FROM`| If you define this constant, all emails will be sent from this address.|
 | `SS_ERROR_LOG` | Relative path to the log file. |

docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md

@@ -37,6 +37,13 @@ SilverStripe\Security\BasicAuth:
   entire_site_protected: true
 ```
 
+The default password protection in this mode (Basic Auth) is an oudated security measure which passes credentials without encryption over the network.
+It is considered insecure unless this connection itself is secured (via HTTPS).
+It also doesn't prevent access to web requests which aren't handled via SilverStripe (e.g. published assets).
+Consider using additional authentication and authorisation measures to secure access (e.g. IP whitelists).
+
+When using CGI/FastCGI with Apache, you will have to add the `RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]` rewrite rule to your `.htaccess` file
+
 ### Live Mode
 
 All error messages are suppressed from the user and the application is in it's most *secure* state.

src/Security/BasicAuth.php

@@ -16,11 +16,16 @@ use SilverStripe\Security\MemberAuthenticator\MemberAuthenticator;
 /**
  * Provides an interface to HTTP basic authentication.
  *
- * This utility class can be used to secure any request with basic authentication.  To do so,
+ * This utility class can be used to secure any request processed by SilverStripe with basic authentication.
- * {@link BasicAuth::requireLogin()} from your Controller's init() method or action handler method.
+ * To do so, {@link BasicAuth::requireLogin()} from your Controller's init() method or action handler method.
  *
  * It also has a function to protect your entire site.  See {@link BasicAuth::protect_entire_site()}
  * for more information. You can control this setting on controller-level by using {@link Controller->basicAuthEnabled}.
+ *
+ * CAUTION: Basic Auth is an oudated security measure which passes credentials without encryption over the network.
+ * It is considered insecure unless this connection itself is secured (via HTTPS).
+ * It also doesn't prevent access to web requests which aren't handled via SilverStripe (e.g. published assets).
+ * Consider using additional authentication and authorisation measures to secure access (e.g. IP whitelists).
  */
 class BasicAuth
 {
@@ -69,7 +74,6 @@ class BasicAuth
      *
      * Used by {@link Controller::init()}.
      *
-     *
      * @param HTTPRequest $request
      * @param string $realm
      * @param string|array $permissionCode Optional
@@ -164,16 +168,19 @@ class BasicAuth
     }
 
     /**
-     * Enable protection of the entire site with basic authentication.
+     * Enable protection of all requests handed by SilverStripe with basic authentication.
      *
      * This log-in uses the Member database for authentication, but doesn't interfere with the
      * regular log-in form. This can be useful for test sites, where you want to hide the site
      * away from prying eyes, but still be able to test the regular log-in features of the site.
      *
      * You can also enable this feature by adding this line to your .env. Set this to a permission
-     * code you wish to require.
+     * code you wish to require: `SS_USE_BASIC_AUTH=ADMIN`
      *
-     * SS_USE_BASIC_AUTH=ADMIN
+     * CAUTION: Basic Auth is an oudated security measure which passes credentials without encryption over the network.
+     * It is considered insecure unless this connection itself is secured (via HTTPS).
+     * It also doesn't prevent access to web requests which aren't handled via SilverStripe (e.g. published assets).
+     * Consider using additional authentication and authorisation measures to secure access (e.g. IP whitelists).
      *
      * @param boolean $protect Set this to false to disable protection.
      * @param string $code {@link Permission} code that is required from the user.