diff --git a/source/manual/how-tos/images/nginx_auth_location.png b/source/manual/how-tos/images/nginx_auth_location.png new file mode 100644 index 00000000..149eccd4 Binary files /dev/null and b/source/manual/how-tos/images/nginx_auth_location.png differ diff --git a/source/manual/how-tos/images/nginx_auth_tls.png b/source/manual/how-tos/images/nginx_auth_tls.png new file mode 100644 index 00000000..72b0530e Binary files /dev/null and b/source/manual/how-tos/images/nginx_auth_tls.png differ diff --git a/source/manual/how-tos/images/nginx_user.png b/source/manual/how-tos/images/nginx_user.png new file mode 100644 index 00000000..d0e9ed66 Binary files /dev/null and b/source/manual/how-tos/images/nginx_user.png differ diff --git a/source/manual/how-tos/images/nginx_users.png b/source/manual/how-tos/images/nginx_users.png new file mode 100644 index 00000000..edfd473f Binary files /dev/null and b/source/manual/how-tos/images/nginx_users.png differ diff --git a/source/manual/how-tos/nginx_basic_auth.rst b/source/manual/how-tos/nginx_basic_auth.rst new file mode 100644 index 00000000..c83727fd --- /dev/null +++ b/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. diff --git a/source/manual/how-tos/nginx_tls_auth.rst b/source/manual/how-tos/nginx_tls_auth.rst new file mode 100644 index 00000000..aa3bbfcf --- /dev/null +++ b/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 + + 400 No required SSL certificate was sent + +

400 Bad Request

+
No required SSL certificate was sent
+
nginx
+ + + +.. 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 diff --git a/source/manual/howtos.rst b/source/manual/howtos.rst index b3313beb..572e2393 100644 --- a/source/manual/howtos.rst +++ b/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