Skip to content

Commit 94715e1

Browse files
k2u2k2u2
committed
Updated docs.
1 parent 5cb1c07 commit 94715e1

18 files changed

+596
-117
lines changed

‎conf/auth-header-path.conf

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,19 @@ default_right = "@admin"
1414

1515
[authz.path_right]
1616
"test" = "@dev"
17+
18+
#[response.ok]
19+
#code=200
20+
#message="Authorized"
21+
22+
#[response.forbidden]
23+
#code=403
24+
#message="Forbidden"
25+
26+
#[response.nopath]
27+
#code=403
28+
#message="No path header"
29+
30+
#[response.nouser]
31+
#code=403
32+
#message="No user header"

‎conf/auth-ldap-path.conf

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ socket_type = "tcp"
22
socket_path = "127.0.0.1:9200"
33
#cache_seconds = 0
44
#use_etag = false
5+
#use_serialized_auth = false
56
auth_realm = "TEST Authentication"
67
path_header = "X-Authz-Path"
78

@@ -28,3 +29,19 @@ default_right = "@admin"
2829

2930
[authz.path_right]
3031
"test" = "@dev"
32+
33+
#[response.ok]
34+
#code=200
35+
#message="Authorized"
36+
37+
#[response.unauth]
38+
#code=401
39+
#message="Not authenticated"
40+
41+
#[response.forbidden]
42+
#code=403
43+
#message="Forbidden"
44+
45+
#[response.nopath]
46+
#code=403
47+
#message="No path header"

‎conf/auth-ldap-path2ldap.conf

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ socket_type = "tcp"
22
socket_path = "127.0.0.1:9200"
33
#cache_seconds = 0
44
#use_etag = false
5+
#use_serialized_auth = false
56
auth_realm = "TEST Authentication"
67
path_header = "X-Authz-Path"
78

@@ -27,3 +28,19 @@ ban_default = true
2728

2829
[authz.path_filter]
2930
"test" = "(&(objectCategory=person)(objectClass=user)(memberOf=CN=Group1,DC=example,DC=com)(userPrincipalName=%s@example.com))"
31+
32+
#[response.ok]
33+
#code=200
34+
#message="Authorized"
35+
36+
#[response.unauth]
37+
#code=401
38+
#message="Not authenticated"
39+
40+
#[response.forbidden]
41+
#code=403
42+
#message="Forbidden"
43+
44+
#[response.nopath]
45+
#code=403
46+
#message="No path header"

‎conf/auth-ldap.conf

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ socket_type = "tcp"
22
socket_path = "127.0.0.1:9200"
33
#cache_seconds = 0
44
#use_etag = false
5+
#use_serialized_auth = false
56
auth_realm = "TEST Authentication"
67

78
host_url = "ldaps://ldap.example.com"
@@ -15,3 +16,11 @@ base_dn = "DC=example,DC=com"
1516
bind_dn = "CN=%s,OU=Users,DC=example,DC=com"
1617
uniq_filter = "(&(objectCategory=person)(objectClass=user)(memberOf=CN=Group1,DC=example,DC=com)(userPrincipalName=%s@example.com))"
1718
timeout = 5000
19+
20+
#[response.ok]
21+
#code=200
22+
#message="Authorized"
23+
24+
#[response.unauth]
25+
#code=401
26+
#message="Not authenticated"

‎conf/auth-simple.conf

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,11 @@ auth_realm = "TEST Authentication"
66
[password]
77
admin1 = "hoge"
88
user1 = "hogehoge"
9+
10+
#[response.ok]
11+
#code=200
12+
#message="Authorized"
13+
14+
#[response.unauth]
15+
#code=401
16+
#message="Not authenticated"

‎docs/ngx_header_path_auth.md

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
[auth request module]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
12
# ngx\_header\_path\_auth
23

3-
**ngx\_header\_path\_auth** is a module for [nginx auth request module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) that authorizes with the user name and path information set in the HTTP header.
4+
**ngx\_header\_path\_auth** is a module for nginx [auth request module] that authorizes with the user name and path information set in the HTTP header.
45

56
## Error handling
67

@@ -19,7 +20,7 @@ start it via a process management system such as systemd.
1920

2021
## Configuration file format
2122

22-
See the [auth request module documentation](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) for how to configure nginx.
23+
See the [auth request module] documentation for how to configure nginx.
2324

2425
The **ngx\_header\_path\_auth** configuration file is in TOML format, and the following is a sample configuration file.
2526

@@ -39,6 +40,22 @@ default_right = "*/
3940
4041
[authz.path_right]
4142
"test" = "@dev"
43+
44+
#[response.ok]
45+
#code=200
46+
#message="Authorized"
47+
48+
#[response.forbidden]
49+
#code=403
50+
#message="Forbidden"
51+
52+
#[response.nopath]
53+
#code=403
54+
#message="No path header"
55+
56+
#[response.nouser]
57+
#code=403
58+
#message="No user header"
4259
```
4360
4461
Each parameter of the configuration file is as follows.
@@ -49,7 +66,9 @@ Each parameter of the configuration file is as follows.
4966
| :--- | :--- |
5067
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
5168
| **socket\_path** | Set the IP address and port number for tcp, and UNIX domain socket file path for unix. |
52-
| **cache\_seconds** | The cache duration in seconds to pass to nginx. However, if its value is 0, it will not use the cache.<br>See [Authentication Cache Control](proxy_cache.md) for details.|
69+
| **cache\_seconds** | Cache duration in seconds passed to nginx upon successful authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
70+
| **neg\_cache\_seconds** | Cache duration in seconds passed to nginx upon failed authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
71+
| **use\_etag** | Set to `true` if you want to validate the cache using the `ETag` tag. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
5372
| **path\_header** | A HTTP header that sets the path used for authorization processing. The default value is `X-Authz-Path`. In the appropriate place of the nginx configuration file, use `proxy_set_header` directive to set the HTTP header. (Eg `proxy_set_header X-Authz-Path $request_uri;`) |
5473
| **user\_header** | A HTTP header to set the user name. The default value is `X-Forwarded-User`. In the appropriate place of the nginx configuration file, use `proxy_set_header` directive to set the HTTP header. (Eg `proxy_set_header X-Forwarded-User $remote_user;`) |
5574
@@ -64,6 +83,34 @@ Each parameter of the configuration file is as follows.
6483
| **default\_right** | Authorization rights when it matches the **path\_pattern**の regular expression and is not specified in **path\_right**. For more information on authorization rights, see "_Authorization rights details_". |
6584
| **path\_right** | Authorization rights map for each extracted string when matching **path\_pattern** regular expression. Specify the extraction string as the key. For more information on authorization rights, see "_Authorization rights details_" section. |
6685
86+
### **\[response.ok\]** part
87+
88+
| Parameter | Description |
89+
| :--- | :--- |
90+
| **code** | The HTTP response status code indicates authorized requests. (Default value: `200`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
91+
| **message** | The HTTP response message indicates authorized requests. (Default value: `"Authorized"`) |
92+
93+
### **\[response.forbidden\]** part
94+
95+
| Parameter | Description |
96+
| :--- | :--- |
97+
| **code** | The HTTP response status code indicates failed authorization requests. (Default value: `403`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
98+
| **message** | The HTTP response message indicates failed authorization requests. (Default value: `"Forbidden"`) |
99+
100+
### **\[response.nopath\]** part
101+
102+
| Parameter | Description |
103+
| :--- | :--- |
104+
| **code** | The HTTP response status code indicates an unexpected HTTP header in **path\_header**. (Default value: `403`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
105+
| **message** | The HTTP response message indicates an unexpected HTTP header in **path\_header**. (Default value: `"No path header"`) |
106+
107+
### **\[response.nouser\]** part
108+
109+
| Parameter | Description |
110+
| :--- | :--- |
111+
| **code** | The HTTP response status code indicates an unexpected HTTP header in **user\_header**. (Default value: `403`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
112+
| **message** | The HTTP response message indicates an unexpected HTTP header in **user\_header**. (Default value: `"No user header"`) |
113+
67114
## Authorization rights details
68115
69116
In **\[authz\]** part, **nomatch\_right**, **default\_right**, and **path\_right** table value specify a character string that combines the following judgment descriptions with `|`. The combined judgment process is calculated by logical disjunction("OR"). If the result is true, it is authorized.
@@ -73,8 +120,8 @@ In **\[authz\]** part, **nomatch\_right**, **default\_right**, and **path\_right
73120
| empty string | Always considers true regardless of the user name. |
74121
| `!` | Always considers false regardless of the user name. |
75122
| `*` | If the user name exists, it is considered true. |
76-
| `@groupname` | The character string after @ is treated as a group name. True if the group contains users. Groups are defined in the **user_map** file. |
77-
| `@` (no group name) | True if the user is described in the **user_map** file. |
123+
| `@groupname` | The character string after @ is treated as a group name. True if the group contains users. Groups are defined in the **user\_map** file. |
124+
| `@` (no group name) | True if the user is described in the **user\_map** file. |
78125
| user name | True if the user name matches. |
79126
80127
## **user\_map\_config** file details

‎docs/ngx_ldap_auth.md

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
[auth request module]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
12
# ngx\_ldap\_auth
23

3-
**ngx\_ldap\_auth** is a module for [nginx auth request module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) that authenticates using an LDAP bind operation.
4+
**ngx\_ldap\_auth** is a module for nginx [auth request module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) that authenticates using an LDAP bind operation.
45

56
## Error handling
67

@@ -9,7 +10,7 @@ On error, the process terminates with an unsuccessful status.
910
## How to start
1011

1112
Run it on the command line like this:
12-
[ngx_header_path_auth](ngx_header_path_auth.md)
13+
[ngx\_header\_path\_auth](ngx_header_path_auth.md)
1314
```
1415
ngx_ldap_auth <config file>
1516
```
@@ -21,15 +22,16 @@ If you want to limit authenticated users by LDAP information, use the LDAP searc
2122

2223
## Configuration file format
2324

24-
See the [auth request module documentation](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) for how to configure nginx.
25+
See the [auth request module] documentation for how to configure nginx.
2526

2627
The **ngx\_ldap\_auth** configuration file is in TOML format, and the following is a sample configuration file.
2728

2829
```ini
2930
socket_type = "tcp"
3031
socket_path = "127.0.0.1:9200"
3132
#cache_seconds = 0
32-
#use_etag = true
33+
#use_etag = false
34+
#use_serialized_auth = false
3335
auth_realm = "TEST Authentication"
3436

3537
host_url = "ldaps://ldap.example.com"
@@ -43,16 +45,28 @@ base_dn = "DC=example,DC=com"
4345
bind_dn = "CN=%s,OU=Users,DC=example,DC=com"
4446
uniq_filter = "(&(objectCategory=person)(objectClass=user)(memberOf=CN=Group1,DC=example,DC=com)(userPrincipalName=%s@example.com))"
4547
timeout = 5000
48+
49+
#[response.ok]
50+
#code=200
51+
#message="Authorized"
52+
53+
#[response.unauth]
54+
#code=401
55+
#message="Not authenticated"
4656
```
4757

4858
Each parameter of the configuration file is as follows.
4959

60+
### Root part
61+
5062
| Parameter | Description |
5163
| :--- | :--- |
5264
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
5365
| **socket\_path** | Set the IP address and port number for tcp, and UNIX domain socket file path for unix. |
54-
| **cache\_seconds** | The cache duration in seconds to pass to nginx. However, if its value is 0, it will not use the cache.<br>See [Authentication Cache Control](proxy_cache.md) for details.|
55-
| **use_etag** | Set to `true` to enable cache validation using `ETag` tags.<br>See [Authentication Cache Control](proxy_cache.md) for details.|
66+
| **cache\_seconds** | Cache duration in seconds passed to nginx upon successful authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
67+
| **neg\_cache\_seconds** | Cache duration in seconds passed to nginx upon failed authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
68+
| **use\_etag** | Set to `true` if you want to validate the cache using the `ETag` tag. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
69+
| **use\_serialized\_auth** | Set to `true` if you want authentication to be serialized for each account. <br>When authentications for the same account conflict, the authentication will be blocked and delayed. |
5670
| **auth\_realm** | HTTP realm string. |
5771
| **host\_url** | The URL of the LDAP server connection address. The pass part is not used. |
5872
| **start\_tls** | Set to 1 when using TLS STARTTLS. |
@@ -62,3 +76,17 @@ Each parameter of the configuration file is as follows.
6276
| **bind\_dn** | This is the bind DN when performing LDAP bind processing. Rewrite `%s` as the remote user name and `%%` as `%`. |
6377
| **uniq\_filter** | Only if this value is set, search with this value filter. If the search result is one DN, the authentication will be successful. |
6478
| **timeout** | Communication timeout(unit: ms) with the LDAP server. |
79+
80+
### **\[response.ok\]** part
81+
82+
| Parameter | Description |
83+
| :--- | :--- |
84+
| **code** | The HTTP response status code indicates authorized requests. (Default value: `200`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
85+
| **message** | The HTTP response message indicates authorized requests. (Default value: `"Authorized"`) |
86+
87+
### **\[response.unauth\]** part
88+
89+
| Parameter | Description |
90+
| :--- | :--- |
91+
| **code** | The HTTP response status code indicates unauthenticated requests. (Default value: `401`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
92+
| **message** | The HTTP response message indicates unauthenticated requests. (Default value: `"Not authenticated"`) |

‎docs/ngx_ldap_path2ldap_auth.md

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
[auth request module]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
12
# ngx\_ldap\_path2ldap\_auth
23

3-
**ngx\_ldap\_path2ldap\_auth** is a module for is a module for [nginx auth request module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) that authenticates using an LDAP bind operation, and authorizes by file path and LDAP information.
4+
**ngx\_ldap\_path2ldap\_auth** is a module for is a module for nginx [auth request module] that authenticates using an LDAP bind operation, and authorizes by file path and LDAP information.
45

56
## Error handling
67

@@ -19,15 +20,16 @@ start it via a process management system such as systemd.
1920

2021
## Configuration file format
2122

22-
See the [auth request module documentation](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) for how to configure nginx.
23+
See the [auth request module] documentation for how to configure nginx.
2324

2425
The **ngx\_ldap\_path2ldap\_auth** configuration file is in TOML format, and the following is a sample configuration file.
2526

2627
```ini
2728
socket_type = "tcp"
2829
socket_path = "127.0.0.1:9203"
2930
#cache_seconds = 0
30-
#use_etag = true
31+
#use_etag = false
32+
#use_serialized_auth = false
3133
auth_realm = "TEST Authentication"
3234
path_header = "X-Authz-Path"
3335

@@ -54,6 +56,22 @@ ban_default = true
5456

5557
[authz.path_filter]
5658
"test" = "(&(objectCategory=person)(objectClass=user)(memberOf=CN=Group1,DC=example,DC=com)(userPrincipalName=%s@example.com))"
59+
60+
#[response.ok]
61+
#code=200
62+
#message="Authorized"
63+
64+
#[response.unauth]
65+
#code=401
66+
#message="Not authenticated"
67+
68+
#[response.forbidden]
69+
#code=403
70+
#message="Forbidden"
71+
72+
#[response.nopath]
73+
#code=403
74+
#message="No path header"
5775
```
5876

5977
Each parameter of the configuration file is as follows.
@@ -64,8 +82,10 @@ Each parameter of the configuration file is as follows.
6482
| :--- | :--- |
6583
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
6684
| **socket\_path** | Set the IP address and port number for tcp, and UNIX domain socket file path for unix. |
67-
| **cache\_seconds** | The cache duration in seconds to pass to nginx. However, if its value is 0, it will not use the cache.<br>See [Authentication Cache Control](proxy_cache.md) for details.|
68-
| **use_etag** | Set to `true` to enable cache validation using `ETag` tags.<br>See [Authentication Cache Control](proxy_cache.md) for details.|
85+
| **cache\_seconds** | Cache duration in seconds passed to nginx upon successful authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
86+
| **neg\_cache\_seconds** | Cache duration in seconds passed to nginx upon failed authentication. If the value is 0, cache will not be used. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
87+
| **use\_etag** | Set to `true` if you want to validate the cache using the `ETag` tag. <br>See [Authentication Cache Control](proxy_cache.md) for details. |
88+
| **use\_serialized\_auth** | Set to `true` if you want authentication to be serialized for each account. <br>When authentications for the same account conflict, the authentication will be blocked and delayed. |
6989
| **auth\_realm** | HTTP realm string. |
7090
| **path\_header** | A HTTP header that sets the path used for authorization processing. The default value is `X-Authz-Path`. In the appropriate place of the nginx configuration file, use `proxy_set_header` directive to set the HTTP header. (Eg `proxy_set_header X-Authz-Path $request_uri;`) |
7191

@@ -86,8 +106,36 @@ Each parameter of the configuration file is as follows.
86106

87107
| Parameter | Description |
88108
| :--- | :--- |
89-
| **path\_pattern** | A regular expression that extracts the authorization judgment string from the path of the header specified by **path_header**. The extracted string is used for the key in **path\_filter**. Use the `()` subexpression regular expression only once to specify the extraction location. |
109+
| **path\_pattern** | A regular expression that extracts the authorization judgment string from the path of the header specified by **path\_header**. The extracted string is used for the key in **path\_filter**. Use the `()` subexpression regular expression only once to specify the extraction location. |
90110
| **ban\_nomatch** | If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **nomatch\_filter** is disabled.) |
91111
| **nomatch\_filter** | LDAP filter for authorization when the **path\_pattern** regular expression is not matched. **nomatch\_filter** results is processed in the same way as **uniq\_filter**. |
92112
| **ban\_default** | If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **default\_filter** is disabled.) |
93113
| **default\_filter** | LDAP filter for authorization rights when it matches the **path\_pattern** regular expression and is not specified in **path\_filter**. **default\_filter** results is processed in the same way as **uniq\_filter**. |
114+
115+
### **\[response.ok\]** part
116+
117+
| Parameter | Description |
118+
| :--- | :--- |
119+
| **code** | The HTTP response status code indicates authorized requests. (Default value: `200`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
120+
| **message** | The HTTP response message indicates authorized requests. (Default value: `"Authorized"`) |
121+
122+
### **\[response.unauth\]** part
123+
124+
| Parameter | Description |
125+
| :--- | :--- |
126+
| **code** | The HTTP response status code indicates unauthenticated requests. (Default value: `401`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
127+
| **message** | The HTTP response message indicates unauthenticated requests. (Default value: `"Not authenticated"`) |
128+
129+
### **\[response.forbidden\]** part
130+
131+
| Parameter | Description |
132+
| :--- | :--- |
133+
| **code** | The HTTP response status code indicates failed authorization requests. (Default value: `403`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
134+
| **message** | The HTTP response message indicates failed authorization requests. (Default value: `"Forbidden"`) |
135+
136+
### **\[response.nopath\]** part
137+
138+
| Parameter | Description |
139+
| :--- | :--- |
140+
| **code** | The HTTP response status code indicates an unexpected HTTP header in **path\_header**. (Default value: `403`)<br>This value is used by the [auth request module]. Therefore, Malfunctions may be caused by the incorrect setting value. |
141+
| **message** | The HTTP response message indicates an unexpected HTTP header in **path\_header**. (Default value: `"No path header"`) |

0 commit comments

Comments
 (0)