Skip to content

Commit caf46a1

Browse files
k2u2k2u2
committed
Updated docs.
1 parent b859851 commit caf46a1

14 files changed

+824
-183
lines changed

‎docs/check_ldap.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,3 @@ check_ldap <config file> <user name>
1616

1717
Execute with the configuration file and user name as arguments.
1818
After execution, enter the password and the result will be output.
19-
20-
The configuration file is the same as [ngx\_ldap\_auth](ngx_ldap_auth.md).

‎docs/ngx_header_path_auth.md

Lines changed: 39 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ See the [auth request module documentation](http://nginx.org/en/docs/http/ngx_ht
2323

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

26-
2726
```ini
2827
socket_type = "tcp"
2928
socket_path = "127.0.0.1:9202"
29+
#cache_seconds = 0
3030
path_header = "X-Authz-Path"
3131
user_header = "X-Forwarded-User"
3232

@@ -43,38 +43,51 @@ default_right = "*/
4343
4444
Each parameter of the configuration file is as follows.
4545
46-
* **socket\_type** - Set this parameter to tcp(TCP socket) or unix(UNIX domain socket).
47-
* **socket\_path** - Set the IP address and port number for tcp, and UNIX domain socket file path for unix.
48-
* **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;`)
49-
* **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;`)
46+
### Root part
47+
48+
| Parameter | Description |
49+
| :--- | :--- |
50+
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
51+
| **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.|
53+
| **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;`) |
54+
| **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;`) |
55+
56+
### **\[authz\]** part
5057
51-
* \[authz\] part
52-
* **user_map** - User name and group name mapping file. More on this in the "_**user\_map** file details_" section.
53-
* **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\_right**. Use the `()` subexpression regular expression only once to specify the extraction location.
54-
* **nomatch\_right** - Authorization rights when the **path\_pattern** regular expression is not matched. For more information on authorization rights, see "_Authorization rights details_" section.
55-
* **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_".
56-
* **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.
58+
| Parameter | Description |
59+
| :--- | :--- |
60+
| **user\_map\_config** | A file that specifies how user names and group names are handled in **user\_map**. More on this in the "_**user\_map\_config** file details_" section. |
61+
| **user_map** | User name and group name mapping file. More on this in the "_**user\_map** file details_" section. |
62+
| **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\_right**. Use the `()` subexpression regular expression only once to specify the extraction location. |
63+
| **nomatch\_right** | Authorization rights when the **path\_pattern** regular expression is not matched. For more information on authorization rights, see "_Authorization rights details_" section. |
64+
| **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_". |
65+
| **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. |
5766
5867
## Authorization rights details
5968
60-
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.
69+
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.
6170
62-
* '' - (empty string) Always considers true regardless of the user name.
63-
* '!' - Always considers false regardless of the user name.
64-
* '*' - If the user name exists, it is considered true.
65-
* '@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.
66-
* '@' - (no group name)　True if the user is described in the **user_map** file.
67-
* 'username` True if the user name matches.
71+
| Authorization method | Description|
72+
| :--- | :--- |
73+
| empty string | Always considers true regardless of the user name. |
74+
| `!` | Always considers false regardless of the user name. |
75+
| `*` | 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. |
78+
| user name | True if the user name matches. |
6879
69-
## **user\_map** file details
80+
## **user\_map\_config** file details
7081
71-
**user\_map** is a text file that defines users and groups.
72-
This text file defines a user-group mapping, with a user name and group names (None or more is possible) on each line, as shown below.
82+
**user\_map\_config** is a file that defines the handling of user names and group names.
83+
This text file defines the available usernames and group names in regular expressions, as shown below.
7384
74-
``` plaintext
75-
user1:group1 group2 ...
76-
...
85+
```
86+
user_regex = '^[a-z_][0-9a-z_\-]{0,32}$'
87+
group_regex = '^[a-z_][0-9a-z_\-]{0,32}$'
7788
```
7889
79-
Separate the user name and group name with `:`. If there are multiple group names, separate them with ` ` (space character).
80-
90+
| Parameter| Description|
91+
| :--- | :--- |
92+
| **user\_regex** | A regular expression of strings to allow as usernames. |
93+
| **group\_regex** | Regular expression of strings to allow as group names. |

‎docs/ngx_ldap_auth.md

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ On error, the process terminates with an unsuccessful status.
99
## How to start
1010

1111
Run it on the command line like this:
12-
12+
[ngx_header_path_auth](ngx_header_path_auth.md)
1313
```
1414
ngx_ldap_auth <config file>
1515
```
@@ -28,6 +28,8 @@ The **ngx\_ldap\_auth** configuration file is in TOML format, and the following
2828
```ini
2929
socket_type = "tcp"
3030
socket_path = "127.0.0.1:9200"
31+
#cache_seconds = 0
32+
#use_etag = true
3133
auth_realm = "TEST Authentication"
3234

3335
host_url = "ldaps://ldap.example.com"
@@ -45,14 +47,18 @@ timeout = 5000
4547

4648
Each parameter of the configuration file is as follows.
4749

48-
* **socket\_type** - Set this parameter to tcp(TCP socket) or unix(UNIX domain socket).
49-
* **socket\_path** - Set the IP address and port number for tcp, and UNIX domain socket file path for unix.
50-
* **auth\_realm** - HTTP realm string.
51-
* **host\_url** - The URL of the LDAP server connection address. The pass part is not used.
52-
* **start\_tls** - Set to 1 when using TLS STARTTLS.
53-
* **skip\_cert\_verify** - Set to 1 to ignore the certificate check result.
54-
* **root\_ca\_files** - A list of PEM files for the CA certificate. Used when the LDAP server is using a certificate from a private CA.
55-
* **base\_dn** - The base DN when connecting to the LDAP server.
56-
* **bind\_dn** - This is the bind DN when performing LDAP bind processing. Rewrite `%s` as the remote user name and `%%` as `%`.
57-
* **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.
58-
* **timeout** - Communication timeout(unit: ms) with the LDAP server.
50+
| Parameter | Description |
51+
| :--- | :--- |
52+
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
53+
| **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.|
56+
| **auth\_realm** | HTTP realm string. |
57+
| **host\_url** | The URL of the LDAP server connection address. The pass part is not used. |
58+
| **start\_tls** | Set to 1 when using TLS STARTTLS. |
59+
| **skip\_cert\_verify** | Set to 1 to ignore the certificate check result. |
60+
| **root\_ca\_files** | A list of PEM files for the CA certificate. Used when the LDAP server is using a certificate from a private CA. |
61+
| **base\_dn** | The base DN when connecting to the LDAP server. |
62+
| **bind\_dn** | This is the bind DN when performing LDAP bind processing. Rewrite `%s` as the remote user name and `%%` as `%`. |
63+
| **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. |
64+
| **timeout** | Communication timeout(unit: ms) with the LDAP server. |

‎docs/ngx_ldap_path2ldap_auth.md

Lines changed: 35 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ The **ngx\_ldap\_path2ldap\_auth** configuration file is in TOML format, and the
2626
```ini
2727
socket_type = "tcp"
2828
socket_path = "127.0.0.1:9203"
29+
#cache_seconds = 0
30+
#use_etag = true
2931
auth_realm = "TEST Authentication"
3032
path_header = "X-Authz-Path"
3133

@@ -56,24 +58,36 @@ ban_default = true
5658

5759
Each parameter of the configuration file is as follows.
5860

59-
* **socket\_type** - Set this parameter to tcp(TCP socket) or unix(UNIX domain socket).
60-
* **socket\_path** - Set the IP address and port number for tcp, and UNIX domain socket file path for unix.
61-
* **auth\_realm** - HTTP realm string.
62-
* **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;`)
63-
64-
* \[ldap\] part
65-
* **host\_url** - The URL of the LDAP server connection address. The pass part is not used.
66-
* **start\_tls** - Set to 1 when using TLS STARTTLS.
67-
* **skip\_cert\_verify** - Set to 1 to ignore the certificate check result.
68-
* **root\_ca\_files** - A list of PEM files for the CA certificate. Used when the LDAP server is using a certificate from a private CA.
69-
* **base\_dn** - The base DN when connecting to the LDAP server.
70-
* **bind\_dn** - This is the bind DN when performing LDAP bind processing. Rewrite `%s` as the remote user name and `%%` as `%`.
71-
* **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.
72-
* **timeout** - Communication timeout(unit: ms) with the LDAP server.
73-
74-
* \[authz\] part
75-
* **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.
76-
* **ban\_nomatch** - If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **nomatch\_filter** is disabled.)
77-
* **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**.
78-
* **ban\_default** - If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **default\_filter** is disabled.)
79-
* **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**.
61+
### Root part
62+
63+
| Parameter | Description |
64+
| :--- | :--- |
65+
| **socket\_type** | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
66+
| **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.|
69+
| **auth\_realm** | HTTP realm string. |
70+
| **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;`) |
71+
72+
### **\[ldap\]** part
73+
74+
| Parameter | Description |
75+
| :--- | :--- |
76+
| **host\_url** | The URL of the LDAP server connection address. The pass part is not used. |
77+
| **start\_tls** | Set to 1 when using TLS STARTTLS. |
78+
| **skip\_cert\_verify** | Set to 1 to ignore the certificate check result. |
79+
| **root\_ca\_files** | A list of PEM files for the CA certificate. Used when the LDAP server is using a certificate from a private CA. |
80+
| **base\_dn** | The base DN when connecting to the LDAP server. |
81+
| **bind\_dn** | This is the bind DN when performing LDAP bind processing. Rewrite `%s` as the remote user name and `%%` as `%`. |
82+
| **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. |
83+
| **timeout** | Communication timeout(unit: ms) with the LDAP server. |
84+
85+
### **\[authz\]** part
86+
87+
| Parameter | Description |
88+
| :--- | :--- |
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. |
90+
| **ban\_nomatch** | If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **nomatch\_filter** is disabled.) |
91+
| **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**. |
92+
| **ban\_default** | If true, authorization will fail if the **path\_pattern** regular expression does not match. (As a result, **default\_filter** is disabled.) |
93+
| **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**. |

0 commit comments

Comments
 (0)