mapcache: document authorization use (#872)

Author: marisn

en/mapcache/http.txt

@@ -54,3 +54,37 @@ request:
     </headers>
   </http>
 
+Authorization
+-------------
+
+To access resources protected by a username and password, provide the `<auth>` element.
+Currently, only basic authentication is supported. Given that usernames and
+passwords are stored in unencrypted form, exercise caution when handling
+the configuration file (e.g., avoid committing it to a public repository and
+set restrictive file access permissions). The same precautions should be taken
+with the memory of the mapcache process (e.g., core files).
+
+.. code-block:: xml
+
+  <http>
+    <url>http://example.com/path?key=value</url>
+    <auth scheme="basic">
+      <user>alice</user>
+      <pass>attackatdawn</pass>
+    </auth>
+  </http>
+
+Both the username and password are processed verbatim. Ensure not to include
+any extra symbols (e.g., space, newline). If there is no username or no password,
+simply leave the respective element empty.
+
+.. code-block:: xml
+
+  <http>
+    <url>http://example.com/path?key=value</url>
+    <auth scheme="basic">
+      <user>bob</user>
+      <pass></pass> <!-- user "bob" has no password -->
+    </auth>
+  </http>
+