Skip to content

Commit 5bb9f43

Browse files
f3lvxf3lvx
committed
Updated docs.
1 parent d46650e commit 5bb9f43

File tree

3 files changed

+498
-0
lines changed

3 files changed

+498
-0
lines changed

‎SpecialThanks.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Special Thx <3
2+
- NGINX, Inc.
3+
- Kiyotaka Doumae
4+
- Junichi Yamaguchi
5+
- Keiichi Shima

‎docs/GettingStarted.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# GettingStarted
2+
3+
## About
4+
5+
This document describes the installation procedure of the ngx\_auth\_mod.
6+
The outline of the installation procesure is shown below.
7+
8+
1. Install nginx
9+
2. Build ngx\_auth\_mod modules
10+
3. Install ngx\_auth\_mod modules
11+
4. Confirm the operation
12+
13+
We will explain each steps with examples.
14+
In the rest of the document, we assume the target distribution is Ubuntu.
15+
The example shown here is to add an authentication function to the configuration of the reverse proxy and web server.
16+
17+
18+
## 1. Install nginx
19+
20+
By using nginx, you can build a HTTP(S) and reverse proxy server etc.
21+
Click [here](https://nginx.org/en/) for an overview of nginx.
22+
23+
### How to install nginx from source code
24+
25+
This section explains how to install nginx from source code.
26+
Note that you need to include [auth request module](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) during the installation procedure, because ngx\_auth\_mod adds an authentication processing to the nginx auth request module.
27+
(Easy installation document can be found from [here](https://nginx.org/en/linux_packages.html))
28+
29+
Install the prerequisites for building nginx:
30+
31+
- `apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev unzip`
32+
33+
Source code for nginx can be downloaded from [here](https://nginx.org/download/).
34+
To install nginx, run the following command:
35+
36+
- `./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`
37+
- `make install`
38+
39+
Finally, place `nginx.service` as a config file of systemd under `/lib/systemd/system/`.
40+
This enables systemd to launch nginx.
41+
FYI, the following is an example of the `nginx.service` file.
42+
43+
```
44+
[Unit]
45+
Description=A high performance web server and a reverse proxy server
46+
After=network.target
47+
48+
[Service]
49+
Type=forking
50+
PIDFile=/run/nginx.pid
51+
ExecStartPre=/usr/local/nginx/sbin/nginx -t -q -g 'daemon on; master_process on;'
52+
ExecStart=/usr/local/nginx/sbin/nginx -g 'daemon on; master_process on;'
53+
ExecReload=/usr/local/nginx/sbin/nginx -g 'daemon on; master_process on;' -s reload
54+
ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid
55+
TimeoutStopSec=5
56+
KillMode=mixed
57+
User=<USER NAME>
58+
Group=<GROUP NAME>
59+
60+
[Install]
61+
WantedBy=multi-user.target
62+
```
63+
64+
## 2. Build ngx\_auth\_mod modules
65+
66+
This section explains how to build ngx\_auth\_mod modules.
67+
68+
### How to install Go
69+
70+
ngx\_auth\_mod modules is written in Go.
71+
You need to install Go to build ngx\_auth\_mod modules.
72+
73+
To download and install Go, click [here](https://go.dev/doc/install).
74+
75+
### How to build ngx\_auth\_mod modules
76+
77+
Follow the steps below to build ngx\_auth\_mod modules.
78+
79+
1. Clone ngx\_auth\_mod repository with the following command
80+
- `git clone <THIS REPOSITORY>`
81+
82+
2. Run the following command to build ngx\_auth\_mod modules:
83+
- `bash /<YOUR WORKING DIRECTORY PATH>/ngx_auth_mod/build.sh`
84+
85+
If the build succeeded, the executable files of each ngx\_auth\_mod module will be placed on ngx\_auth\_mod/bin/.
86+
The documents of each modules are available in separate pages.
87+
88+
- ngx\_ldap\_auth module
89+
- [documentation of ngx\_ldap\_auth](../docs/README.md#ngx_ldap_auth)
90+
- ngx\_ldap\_path\_auth module
91+
- [documentation of ngx\_ldap\_path\_auth](../docs/README.md#ngx_ldap_path_auth)
92+
- ngx\_header\_path\_auth module
93+
- [documentation of ngx\_header\_path\_auth](../docs/README.md#ngx_header_path_auth)
94+
- ngx\_ldap\_path2ldap\_auth module
95+
- [documentation of ngx\_ldap\_path2ldap\_auth](../docs/README.md#ngx_ldap_path2ldap_auth)
96+
97+
Select any of the authentication module depending on your requirement and place it to the location you prefer.
98+
In the next section, the ngx\_ldap\_auth module will be used as an example.
99+
100+
## 3. Install ngx\_auth\_mod modules
101+
102+
In this section, we will explain how to install the ngx\_auth\_mod modules by following the steps shown below.
103+
104+
1. How to configure LDAP authentication(/authorization)
105+
2. How to configure authentication of nginx
106+
3. How to create a systemd configuration file for ngx\_auth\_mod
107+
108+
### How to configure LDAP authentication(/authorization)
109+
110+
Create authentication(/authorization) restrictions according to the module you are using.
111+
You can find an example config file from [here](../conf/).
112+
The documents of each configuration file are provided separately.
113+
114+
- ngx\_ldap\_auth module
115+
- [documentation of ngx\_ldap\_auth configuration file](../docs/ngx_ldap_auth.md)
116+
- ngx\_ldap\_path\_auth module
117+
- [documentation of ngx\_ldap\_path\_auth configuration file](../docs/ngx_ldap_path_auth.md)
118+
- ngx\_header\_path\_auth module
119+
- [documentation of ngx\_header\_path\_auth configuration file](../docs/ngx_header_path_auth.md)
120+
- ngx\_ldap\_path2ldap\_auth module
121+
- [documentation of ngx\_ldap\_path2ldap\_auth configuration file](../docs/ngx_ldap_path2ldap_auth.md)
122+
123+
In this GettingStarted documentation, ngx\_ldap\_auth module is used as an example.
124+
Therefore, edit the `auth-ldap.conf` file to fit your LDAP schema.
125+
Also, place the `auth-ldap.conf` file anywhere.
126+
127+
### How to configure authentication of nginx
128+
129+
The configuration file (`nginx.conf`) is placed under `/usr/local/nginx/conf/`.
130+
Add the following line to the `nginx.conf` file.
131+
132+
- `include /usr/local/nginx/sites-enabled/*.conf;`
133+
134+
Create a directory with the following command:
135+
136+
- `mkdir /usr/local/nginx/sites-available`
137+
- `mkdir /usr/local/nginx/sites-enabled`
138+
139+
These directories are popular directries when customising nginx.
140+
141+
Next, create a new configuration file of nginx as `auth-webserver.conf`.
142+
This configuration file is used to launch reverse proxy (443/TCP), web server (80/TCP), and ngx\_auth\_mod module (Any port number/TCP).
143+
FYI, an example `auth-webserver.conf` is shown below.
144+
145+
```
146+
# ngx_ldap_auth module service
147+
upstream auth_req { server 127.0.0.1:<MODULE PORT>; }
148+
149+
# Reverse proxy(443/TCP)
150+
server {
151+
listen 443 default ssl;
152+
server_name localhost;
153+
ssl_certificate <YOUR SSL CERTIFICATE FILE PATH>;
154+
ssl_certificate_key <YOUR SSL CERTIFICATE KEY FILE PATH>;
155+
ssl_protocols TLSv1.2 TLSv1.3;
156+
ssl_ciphers HIGH:!aNULL:!MD5;
157+
ssl_prefer_server_ciphers on;
158+
ssl_session_cache shared:SSL:10m;
159+
ssl_session_timeout 10m;
160+
client_max_body_size 1G;
161+
162+
root /<YOUR WEB SERVER's ROOT DIRECTORY PATH>/var/www/dummy; # Don't create a dummy file.
163+
164+
# Authentication URL path
165+
auth_request /auth;
166+
proxy_set_header Authorization "";
167+
location = /auth {
168+
proxy_set_header X-Forwarded-User $remote_user; # Required if using modules other than ngx_ldap_auth.
169+
proxy_set_header Context-Length "";
170+
proxy_pass_request_body off;
171+
proxy_pass http://auth_req;
172+
}
173+
174+
proxy_intercept_errors on;
175+
error_page 400 403 404 500 502 503 /error/error.html;
176+
error_page 405 415 /error/;
177+
location /error/ {
178+
auth_request off;
179+
access_log off;
180+
add_header Cache-Control "maxage-86400, public";
181+
}
182+
183+
location / {
184+
proxy_set_header Context-Length "";
185+
proxy_pass http://localhost:80/;
186+
}
187+
}
188+
# Web Server(80/TCP)
189+
server {
190+
listen 80 default;
191+
192+
server_name localhost;
193+
client_max_body_size 1G;
194+
root /<YOUR WEB SERVER's ROOT DIRECTORY PATH>/var/www;
195+
196+
location / {
197+
index index.html;
198+
}
199+
200+
proxy_intercept_errors on;
201+
error_page 400 403 404 500 502 503 /error/error.html;
202+
error_page 405 415 /error/;
203+
location /error/ {
204+
auth_request off;
205+
access_log off;
206+
add_header Cache-Control "maxage-86400, public";
207+
}
208+
}
209+
```
210+
211+
We recommend to use SSL/TLS protocols to use authentication information.
212+
Prepare HTML files by yourself.
213+
Finally, place the `auth-webserver.conf` file under the `sites-available` and `sites-enabled` directories.
214+
215+
### How to create a systemd configuration file of ngx\_auth\_mod module
216+
217+
Finally, place the `ngx_auth_ldap.service` file used by systemd under `/lib/systemd/system/`.
218+
This enables systemd to launch the ngx\_auth\_ldap module.
219+
FYI, the following is an example of the `ngx_auth_ldap.service` file.
220+
221+
```
222+
[Unit]
223+
Description=LDAP authentication service for nginx
224+
After=nginx.service
225+
226+
[Service]
227+
ExecStart=/<YOUR MODULE PATH>/ngx_ldap_auth /<YOUR MODULE CONFIG FILE PATH>/auth-ldap.conf
228+
User=<ACCOUNT NAME>
229+
Group=<GROUP NAME>
230+
```
231+
232+
## 4. Confirm the operation
233+
234+
Finally, make sure the operation of nginx and ngx\_auth\_mod module.
235+
236+
### Launch of nginx and ngx\_auth\_mod service
237+
238+
Run the following commands to launch nginx and the ngx\_auth\_mod module:
239+
240+
- `systemctl start nginx.service`
241+
- `systemctl start ngx_auth_ldap.service`
242+
243+
### Confirmation of authentication process
244+
245+
Run the following command to confirm the authentication process is working:
246+
247+
- `curl https://127.0.0.1 -H --basic -u <USER>:<PASS>`
248+
249+
Have a good Authentication life <3

0 commit comments

Comments
 (0)