locosync/apache_2f repository overview

This is an Apache server with 2 factor authentication, mainly intended for use as a reverse proxy to publish internal web services.

v0.3 is an early release, and it is considered an alpha version. If you have any question, comments, please feel free to contact me.

The solution is based on https://github.com/itemir/apache_2fa⁠

⁠Table of contents

1. How to run it⁠
2. Adding users⁠
3. Adding content⁠
4. Adding certificates⁠
5. Set the server name and server admin⁠
6. Internals⁠
7. Docker tricks⁠
8. Troubleshooting⁠
9. ToDo⁠

⁠How to run it

The easiest way to test it out is by creating a directory called a2f and running the following command:

docker run --name apache_2f\ 
	-p 4443:443\ 
	-v `pwd`/a2f:/usr/local/apache2/conf/a2f\
	locosync/apache_2f

This will create a container with the web server, running on port 4443, with a self signed certificate. To test it, point your browser to https://localhost:4443⁠. To login use test_user and test_password. For the second factor install Google Authenticator on your phone and scan the following QR code or enter the code manually: ND4LKCSFMUQISO6CBZQATLDP .

⁠Adding users

In the a2f directory created, there are the apache_credentials and the tokens.json files.

Adding username and password

To add the user name and password, use the htdigest command. (You may need to use root rights with sudo -s.)

htdigest a2f/apache_credentials "Secure Site" newusername

. "Secure Site" is the realm or login prompt, for the authentication. This is the default value, later you will see how to change it. If you don't have htdigest command on your computer, you can do the same inside the docker container:

docker exec -ti apache_2f bash
htdigest /usr/local/apache2/conf/a2f/apache_credentials "Secure Site" newusername
CTRL-D - to exit the container

. Adding Google Authenticator code

First create a 15 char long base32 encoded token:

head -c 15 /dev/urandom | base32

. First you need to add this to the a2f/tokens.json, in the form of

Then either type in the code to Google Authenticator or go to the home page of the newly created secure site, select the "Token QR code maker", enter the date and scan the generated QR code. On the page, the server name is mandatory, but both server name and user name are only used to identify the token within Google Authenticator. On the page the URL is shown, which is used to generate the QR code, if you have specific needs, you can construct the URL directly.

When you go productive do not forget to delete the test_user :-)

⁠Adding content

This container is not intended to be used a web server, its main purpose is to provide a gateway to internal web sites. Despite this you can add some static content, what can be used to create a menu to access the different internal sites.

Adding static web pages To Add static content, crate folder htdocs and in the docker run command map it to the /usr/local/apache2/htdocs directory.

docker run --name apache_2f -p 4443:443\
		-v a2f:/usr/local/apache2/conf/a2f\
		-v htdocs:/user/local/apache2/htdocs\
		locosync/apache_2f

. Now whatever you put in htdocs will be in the root folder of the website.

Adding redirects For redirects, we use Apache's reverse proxy capabilities. See more details here⁠. To create a simple redirect, create a new file in a2f/redirects with the extension conf and put something similar to the next example into it. Then restart the container

docker restart apache_2f  

. or restart apache within the container:

apachectl -k restart 

. Example a2f/redirecs/internal.conf:

<Location /internalweb/>
    Order allow,deny 
    Allow from all 
    ProxyPass http://internal.site.local/
    ProxyPassReverse http://internal.site.local/
</Location>

. If you got to yoursite/internalweb/ you can access the internal site. Training slashes are important, both in the ProxyPass directives and when accessing the site.

⁠Adding certificates

The cerificate and key files are located in

a2f/server.crt.pem
a2f/server.key

. Customizing self signed certificate

If the container doesn't find ceritificate and key files here, it will create a self signed one with the subject: "/C=US/ST=New York/L=New York/O=SecureSite/OU=SecureSite/CN=secure.local". To change this subject, delete the certificate and key files, override this subject in a2f/cert_subject.sh and restart the container.

Adding real certificate

To create "real" certificates, follow some of the online tutorial, or go to ZeroSSL⁠ and create one using the online tools. I have tried ZeroSSL with DNS validation, and within 5 minutes I had my certificates. After obtaining the certificate stop the container

docker container stop apache_2f

. copy the new certificates to a2f/server.key and a2f/server.crt.pem and restart the container

docker container start apache_2f

. Check logs to see if everything went good:

docker logs apache_2f

⁠. Set the server name and server admin

Tho have the server configured nicely you may add the ServerName and ServerAdmin directives. In the file a2f/servername.conf you can add the following directives:

ServerName your.server.name.com
ServerAdmin [email protected]

. Also here you can change the authentication realm:

Define LoginPromptText "Secure Site"

. But remember if you change "Secure Site" you need to thange the authentication passwords in apache_credentials, as described in the add users section.

⁠Internals

Inside the image the following data structure is used

Directories:

/usr/local/a2f - custom files, location of authentication scripts /usr/local/apache2/htdocs - apache root document folder /usr/local/apache2/conf - apache configuration directory /usr/local/apache2/conf/extras/httpd-ssl.conf - https configuration + apache configuration of the token authentication /usr/local/apache/conf/a2f - solution specific configuration volume - here is where we have to put our configuration, and this is exposed to the outside a2f directory /usr/local/apache2/conf/a2f/redirects - all *.conf files are included (mainly for redirects)

Files in /usr/local/apache2/conf/a2f

servername.conf - ServerName and ServerAdmin directives apache_credentials - authentication for apache tokens.json - google authenticator tokens server.crt.pem server.key

servername.conf is read in at the begining of Apache configuration. Here it is possible to add global Apache configuration directives. a2f/redirects is read inside the secure site configuration of apache. Here can be put additional directives needed for the site configuration.

⁠Docker tricks

Use the

docker [start|stop|restart] apache_2f

. command to manage the container.

Use the following command to list and delete containers:

docker container ls (-a)
docker container rm apache_2f

. If you append -d to the run command above, then the container starts in the background, if you want to see the output, type:

docker logs apache_2f

. You may append --restart always to the run command, in this case even if the host computer is restarted, this container will start automatically.

Use

docker exec -ti apache_2f bash

. to get into the container and execute commands there. Also if you do not know the 3 command needed for vi (i,<esc>, :wq) or simply do not like vi as an editor, you can install nano in the container:

apk add nano

⁠. Troubleshooting

Docker containers tend to use the standard google name servers 8.8.8.8 and 4.4.4.4 for name lookup. This can be a reason not being able to connect to internal sites. Within the container change the /etc/resolv.conf to the desired value. The Apache error log is stored under /usr/local/apche2/log/error.log If redirects are not working, often you can find some error messages here.

⁠ToDo

• implement user management commands
• if feasible implement ZeroSSL certificate regular renewal