www/nginx: add authentication via TLS/Basic (#40)

source/manual/how-tos/nginx_basic_auth.rst

@@ -0,0 +1,87 @@
+===========================================
+nginx: Basic Authentication & Authorization
+===========================================
+
+.. Warning::
+
+    Passwords in password files cannot be stored securely.
+    Your passwords are stored in plain text in the configuration and as md5 in the
+    nginx password files. Secure password hashes like bcrypt_, scrypt_ or
+    Argon_ 2 are currently not supported by nginx.
+    
+    Please also note that basic authentication transfers the credentials in plain text
+    to the server. It is recommended that you only use it via HTTPS because otherwise
+    every attacker with a network sniffer such as Wireshark_ (and mabe some additional
+    man in the middle tools like ettercap_ or fake_router6_) will be able to intercept
+    your connection to the server and read your password.
+
+.. _Argon: https://github.com/P-H-C/phc-winner-argon2
+.. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
+.. _scrypt: https://en.wikipedia.org/wiki/Scrypt
+.. _Wireshark: https://www.wireshark.org/
+.. _ettercap: https://www.ettercap-project.org/
+.. _fake_router6: https://github.com/vanhauser-thc/thc-ipv6
+
+
+Background Information
+======================
+
+Basic authentication encodes the username and the password in Base64 in a HTTP header.
+Because it is really simple to implement, almost every HTTP client supports it.
+For this reason, people use it to protect REST interfaces and so on.
+Also authentication for the OPNsense API supports this kind of authentication.
+
+Configuration
+=============
+
+Create Users
+------------
+
+Navigate to the "Credential" tab.
+
+.. image:: images/nginx_user.png
+
+Enter a username and a password and press ok
+
+Create An User List
+-------------------
+
+Navigate to the tab "User List".
+
+.. image:: images/nginx_users.png
+
+Select all users, that should have access to a specific resource and give this group a name.
+
+
+Assign it to a Location
+-----------------------
+
+In the last step, the user list must be added to the location.
+
+.. image:: images/nginx_auth_location.png
+
+As soon as you restart the server,
+you will need to log in to access the contents of this directory.
+To do so, you can enter any string in the basic authentication field,
+which will be sent as an realm. The user list is the list previously
+created.
+
+Reload the server.
+
+Testing
+=======
+
+You can use curl to check if it works. In a browser like Firefox, a dialog asking for credentials should open.
+
+.. code-block:: sh
+
+    curl -v -u user:password  "http://example.com/restricted/image.png"
+
+Advanced Authentication
+=======================
+
+The entry advanced authentication is used to call an external authentication
+provider. In the case of OPNsense, this is currently a special script,
+which authenticates agains the local database. If you want to use it,
+do not enter a realm nor select a user list.
+Please note that this feature may change in the future.

source/manual/how-tos/nginx_tls_auth.rst

@@ -0,0 +1,56 @@
+=========================================
+nginx: TLS Authentication & Authorization
+=========================================
+
+.. Warning::
+
+    Even if this is probably the most secure way to authenticate,
+    a lot of clients do not support it or I may be hard for users
+    to configure it.
+    
+    This authentication mechanism is recommended for machine to
+    machine communication and experienced users.
+
+
+Background Information
+======================
+
+TLS authentication happens when the HTTPS connection is set up and for
+this reason you can not configure it per directory (this information has
+not been received yet). If you want to use this authentication type in
+a custom application, the nginx plugin configures nginx to send you
+the required information like the CN).
+
+Configuration
+=============
+
+First of all, you need a CA, a client and a server certificate.
+
+Please create it like described in :doc:`sslvpn_client`. If you want,
+that your VPN users can log into your application using the same certificate,
+you may use the same CA.
+
+.. image:: images/nginx_auth_tls.png
+
+Next, choose the CA, the certificate and choose *on* as for client validation.
+This will reject any connection by a client, who has no valid certificate.
+
+Testing
+=======
+
+.. code-block:: none
+
+    curl https://192.168.1.1:444/file.txt --cacert ../MyOPNsenseCA.crt 
+    <html>
+    <head><title>400 No required SSL certificate was sent</title></head>
+    <body bgcolor="white">
+    <center><h1>400 Bad Request</h1></center>
+    <center>No required SSL certificate was sent</center>
+    <hr><center>nginx</center>
+    </body>
+    </html>
+
+.. code-block:: none
+
+    curl https://192.168.1.1:444/file.txt --cert ../nginx_client_test_cert.crt --key ../nginx_client_test_cert.key --cacert ../MyOPNsenseCA.crt
+    Hello World

source/manual/howtos.rst

@@ -41,6 +41,8 @@ How to's
    how-tos/netflow_exporter
    how-tos/nginx
    how-tos/nginx_hosting
+   how-tos/nginx_basic_auth
+   how-tos/nginx_tls_auth
    how-tos/nginx_waf
    how-tos/openconnect
    how-tos/orange_fr_fttp