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.
On error, the process terminates with an unsuccessful status.
Run it on the command line like this:
ngx_header_path_auth <config file>
Since it does not provide background execution functions such as daemonization, start it via a process management system such as systemd.
See the auth request module documentation for how to configure nginx.
The ngx_header_path_auth configuration file is in TOML format, and the following is a sample configuration file.
socket_type = "tcp"
socket_path = "127.0.0.1:9202"
#cache_seconds = 0
path_header = "X-Authz-Path"
user_header = "X-Forwarded-User"
[authz]
user_map = "/etc/ngx_auth_mod/usermap.conf"
path_pattern = "^/([^/]+)/"
nomatch_right = "@admin"
default_right = "*/
[authz.path_right]
"test" = "@dev"Each parameter of the configuration file is as follows.
| Parameter | Description |
|---|---|
| socket_type | Set this parameter to tcp(TCP socket) or unix(UNIX domain socket). |
| socket_path | Set the IP address and port number for tcp, and UNIX domain socket file path for unix. |
| cache_seconds | The cache duration in seconds to pass to nginx. However, if its value is 0, it will not use the cache. See Authentication Cache Control for details. |
| 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;) |
| 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;) |
| Parameter | Description |
|---|---|
| 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. |
| user_map | User name and group name mapping file. More on this in the "user_map file details" section. |
| 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. |
| nomatch_right | Authorization rights when the path_pattern regular expression is not matched. For more information on authorization rights, see "Authorization rights details" section. |
| 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". |
| 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. |
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.
| Authorization method | Description |
|---|---|
| empty string | Always considers true regardless of the user name. |
! |
Always considers false regardless of the user name. |
* |
If the user name exists, it is considered true. |
@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. |
@ (no group name) |
True if the user is described in the user_map file. |
| user name | True if the user name matches. |
user_map_config is a file that defines the handling of user names and group names.
This text file defines the available usernames and group names in regular expressions, as shown below.
user_regex = '^[a-z_][0-9a-z_\-]{0,32}$'
group_regex = '^[a-z_][0-9a-z_\-]{0,32}$'
| Parameter | Description |
|---|---|
| user_regex | A regular expression of strings to allow as usernames. |
| group_regex | Regular expression of strings to allow as group names. |