Skip to content

Latest commit

 

History

History
249 lines (183 loc) · 8.56 KB

GettingStarted.md

File metadata and controls

249 lines (183 loc) · 8.56 KB

GettingStarted

About

This document describes the installation procedure of the ngx_auth_mod.
The outline of the installation procesure is shown below.

  1. Install nginx
  2. Build ngx_auth_mod modules
  3. Install ngx_auth_mod modules
  4. Confirm the operation

We will explain each steps with examples.
In the rest of the document, we assume the target distribution is Ubuntu.
The example shown here is to add an authentication function to the configuration of the reverse proxy and web server.

1. Install nginx

By using nginx, you can build a HTTP(S) and reverse proxy server etc.
Click here for an overview of nginx.

How to install nginx from source code

This section explains how to install nginx from source code.
Note that you need to include auth request module during the installation procedure, because ngx_auth_mod adds an authentication processing to the nginx auth request module.
(Easy installation document can be found from here)

Install the prerequisites for building nginx:

  • apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev unzip

Source code for nginx can be downloaded from here.
To install nginx, run the following command:

  • ./configure --prefix=/usr/local/nginx --pid-path=/run/nginx.pid --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --with-http_ssl_module --with-http_v2_module --with-http_auth_request_module
  • make install

Finally, place nginx.service as a config file of systemd under /lib/systemd/system/.
This enables systemd to launch nginx.
FYI, the following is an example of the nginx.service file.

[Unit]
Description=A high performance web server and a reverse proxy server
After=network.target

[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStartPre=/usr/local/nginx/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/local/nginx/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/local/nginx/sbin/nginx -g 'daemon on; master_process on;' -s reload
ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid
TimeoutStopSec=5
KillMode=mixed
User=<USER NAME>
Group=<GROUP NAME>

[Install]
WantedBy=multi-user.target

2. Build ngx_auth_mod modules

This section explains how to build ngx_auth_mod modules.

How to install Go

ngx_auth_mod modules is written in Go.
You need to install Go to build ngx_auth_mod modules.

To download and install Go, click here.

How to build ngx_auth_mod modules

Follow the steps below to build ngx_auth_mod modules.

  1. Clone ngx_auth_mod repository with the following command

    • git clone <THIS REPOSITORY>

  2. Run the following command to build ngx_auth_mod modules:

    • bash /<YOUR WORKING DIRECTORY PATH>/ngx_auth_mod/build.sh

If the build succeeded, the executable files of each ngx_auth_mod module will be placed on ngx_auth_mod/bin/.
The documents of each modules are available in separate pages.

Select any of the authentication module depending on your requirement and place it to the location you prefer.
In the next section, the ngx_ldap_auth module will be used as an example.

3. Install ngx_auth_mod modules

In this section, we will explain how to install the ngx_auth_mod modules by following the steps shown below.

  1. How to configure LDAP authentication(/authorization)
  2. How to configure authentication of nginx
  3. How to create a systemd configuration file for ngx_auth_mod

How to configure LDAP authentication(/authorization)

Create authentication(/authorization) restrictions according to the module you are using.
You can find an example config file from here.
The documents of each configuration file are provided separately.

In this GettingStarted documentation, ngx_ldap_auth module is used as an example.
Therefore, edit the auth-ldap.conf file to fit your LDAP schema.
Also, place the auth-ldap.conf file anywhere.

How to configure authentication of nginx

The configuration file (nginx.conf) is placed under /usr/local/nginx/conf/.
Add the following line to the nginx.conf file.

  • include /usr/local/nginx/sites-enabled/*.conf;

Create a directory with the following command:

  • mkdir /usr/local/nginx/sites-available
  • mkdir /usr/local/nginx/sites-enabled

These directories are popular directries when customising nginx.

Next, create a new configuration file of nginx as auth-webserver.conf.
This configuration file is used to launch reverse proxy (443/TCP), web server (80/TCP), and ngx_auth_mod module (Any port number/TCP).
FYI, an example auth-webserver.conf is shown below.

# ngx_ldap_auth module service
upstream auth_req { server 127.0.0.1:<MODULE PORT>; }

# Reverse proxy(443/TCP)
server {
	listen 443 default ssl;
	server_name localhost;
	ssl_certificate <YOUR SSL CERTIFICATE FILE PATH>;
	ssl_certificate_key <YOUR SSL CERTIFICATE KEY FILE PATH>;
	ssl_protocols TLSv1.2 TLSv1.3;
	ssl_ciphers HIGH:!aNULL:!MD5;
	ssl_prefer_server_ciphers on;
	ssl_session_cache shared:SSL:10m;
	ssl_session_timeout 10m;
	client_max_body_size 1G;

	root /<YOUR WEB SERVER's ROOT DIRECTORY PATH>/var/www/dummy; # Don't create a dummy file.

	# Authentication URL path
	auth_request /auth;
	proxy_set_header Authorization "";
	location = /auth {
		proxy_set_header X-Forwarded-User $remote_user; # Required if using modules other than ngx_ldap_auth.
		proxy_set_header Context-Length "";
		proxy_pass_request_body off;
		proxy_pass http://auth_req;
	}

	proxy_intercept_errors on;
	error_page 400 403 404 500 502 503 /error/error.html;
	error_page 405 415 /error/;
	location /error/ {
		auth_request off;
		access_log off;
		add_header Cache-Control "maxage-86400, public";
	}

	location / {
		proxy_set_header Context-Length "";
		proxy_pass http://localhost:80/;
	}
}
# Web Server(80/TCP)
server {
	listen 80 default;

	server_name localhost;
	client_max_body_size 1G;
	root /<YOUR WEB SERVER's ROOT DIRECTORY PATH>/var/www;

	location / {
		index index.html;
	}

	proxy_intercept_errors on;
	error_page 400 403 404 500 502 503 /error/error.html;
	error_page 405 415 /error/;
	location /error/ {
		auth_request off;
		access_log off;
		add_header Cache-Control "maxage-86400, public";
	}
}

We recommend to use SSL/TLS protocols to use authentication information.
Prepare HTML files by yourself.
Finally, place the auth-webserver.conf file under the sites-available and sites-enabled directories.

How to create a systemd configuration file of ngx_auth_mod module

Finally, place the ngx_auth_ldap.service file used by systemd under /lib/systemd/system/.
This enables systemd to launch the ngx_auth_ldap module.
FYI, the following is an example of the ngx_auth_ldap.service file.

[Unit]
Description=LDAP authentication service for nginx
After=nginx.service

[Service]
ExecStart=/<YOUR MODULE PATH>/ngx_ldap_auth /<YOUR MODULE CONFIG FILE PATH>/auth-ldap.conf
User=<ACCOUNT NAME>
Group=<GROUP NAME>

4. Confirm the operation

Finally, make sure the operation of nginx and ngx_auth_mod module.

Launch of nginx and ngx_auth_mod service

Run the following commands to launch nginx and the ngx_auth_mod module:

  • systemctl start nginx.service
  • systemctl start ngx_auth_ldap.service

Confirmation of authentication process

Run the following command to confirm the authentication process is working:

  • curl https://127.0.0.1 -H --basic -u <USER>:<PASS>

Have a good Authentication life <3