nggroup (nginx htgroup)
Group ACLs for Basic HTTP Authentication with Nginx
Basic HTTP authentication is a simple popup for a username/password combination that is rendered by the browser, and handled by the web server. This authentication is implemented in both major web servers, Apache and Nginx, via the
.htpasswd files. In addition to having control over users with access to a site or directory, Apache also has the ability to assign groups for more fine grained access control. However, nginx does not - this tool aims to fix that.
nggroup is a tool hoping to solve this issue by allowing sysadmins to generate their own group files. A global collection of users and groups can be accessed, and then can be fed into user-generated sites. The generated files can then be used by nginx as authentication files, as they are the format of the
As has been answered on StackOverflow, there is some need for this. As I myself have to manage a server like this, with ~100 and ~20 groups, I found making a tool to solve this issue would be a good course of action. Relevant XKCD.
Note: This system is not written to be completely secure. Passwords are entered stored in plaintext and cannot be changed by users. Ensure that no passwords stored in this system are passwords any user normally uses. Please also note that basic HTTP authentication does not encrypt passwords in transit. As such, to increase security, ensure the nginx server you are using this tool with is running HTTPS.
The only command that is needed in order to run this tool is
htpasswd, which is included in:
Testing locally does not require any special steps to run, provided the above dependency is met. You will be able to start straight away by running
Note that the working directory will be the directory that
nggroup resides in.
Running in Production
In order to install
nggroup, you will need to:
- Set a global environment variable,
$_IN_PRODUCTIONto i.e. your hostname (as long as it is non-null). This is best set in the
/etc/environmentfile. Remember to
source /etc/environmentto ensure that the variable is set.
- Copy this repository to somewhere in the
$PATH, ensuring that only
nggrouphas execute rights.
Once complete, you will be able to start by running
nggroup <cmd> from any directory.
Note that the working directory will be the
NOTE: In order for any changes you make to become live, you will need to run
Adding a New User and Site
nggroup siteadd newsite nggroup useradd testuser testpwd noone@localhost "User Name" nggroup sitemod newsite +testuser nggroup generate
Creating a Group for a Site
nggroup groupadd testgroup nggroup useradd testuser1 testpwd1 noone@localhost "User Name" nggroup useradd testuser2 testpwd2 nowhere@localhost "Name User" nggroup sitemod newsite +@testgroup nggroup generate
Delete a Group
nggroup groupdel testgroup
NOTE: This will remove all references to the group. Any sites that require the group will now not have the group, or the users that were in said group. Also note that this applies to users and sites.
Full Command Listing
To see a less verbose listing, please run
||add a new site|
||remove the site|
||add user to site|
||remove user from site|
||add group to site|
||remove group from site|
||add a new group|
||remove the group|
||add user to group|
||remove user from group|
||add a new user|
||remove a user|
||generate all user, site and group files|
Note that when removing performing
(user|group)del you will remove all references to it.
Remember to quote names when adding users - i.e. "Jamie Tanna", otherwise only the first name will be used.
- None I have found - if you find one, please create an Issue on Github.
Future Features (?)
The following features are subject to change, but will most probably be added as they'll make my life easier:
- dry run mode
- ability to go through all the changes that we're going to make, and any potential issues
nggroup setup file.csv
- output how many tests done/left
- if passwd = "-" ; read interactively
- generate random passwords
- remove trailing spaces sed -i 's/[ \t]$//' $(find . -path '/.git' -prune -o -type f -print)
- i.e. nggroupXXX
- list emails stored
nggroup emails (|user|group)