Mod_authz_unixgroup

Author and Maintainer: Jan Wolter email
Mailing List: mod_auth_external@googlegroups.com

Introduction:

Mod_Authz_Unixgroup is a unix group access control module for Apache 2.1 and later. If you are having users authenticate with real Unix login ID over the net, using something like my mod_authnz_external / pwauth\ combination, and you want to do access control based on unix group membership, then mod_authz_unixgroup is exactly what you need.

Let's say you are doing unix passwd file authentication with mod_authnz_external and pwauth. Your .htaccess file for a protected directory would probably start with the following directives:

AuthType Basic
AuthName mysite
AuthBasicProvider external
AuthExternal pwauth

That would cause mod_auth_basic and mod_authnz_external to do authentication based on the Unix passwd database. Mod_Authz_Unixgroup would come into play if you wanted to further restrict access to specific Unix groups. You might append the following directives:

AuthzUnixgroup on
Require group staff admin

This would allow only access to accounts in the 'staff' or 'admin' unix groups. You can alternately specify groups by their gid numbers instead of their names.

Though it makes the most sense to use mod_authz_unixgroup with unix passwd authentication, it can be used with other databases. In that case it would grant access if, (1) the name the user authenticated with exactly matched the name of a real unix account on the server, and (2) that real unix account was in one of the required groups. However, I think this would be a pretty senseless way to use this module. I expect that it will really only be used by users of mod_authnz_external and pwauth or other similar software.

Some authentication modules, like mod_auth_kerb, use usernames that have domains appended to them, like "whomever@krb.ncsu.edu". In such cases, mod_authz_unixgroup will take the part before the @-sign as the username and ignore the rest.

It will come as no surprise that this module works only on Unix systems. It should work on pretty much any vaguely modern Unix.

Installation and Configuration

To install the module in Apache, you follow pretty much the same procedure as for mod_auth_external.

If you want to use it in a particular directory, then you must insert some commands into the .htaccess file for the directory or a appropriate <Directory> block in httpd.conf.

First you need to turn mod_authz_unixgroup on for the directory:

AuthzUnixgroup on

Next you'll need a require directive like

Require group admin

or

Require group students teachers staff

The second version allows a person to have access to the directory if he is in any one of the listed groups. You can identify groups using their group id numbers rather than their names, if you prefer.

Obviously this only makes sense in a directory where you are doing authentication. This could be any kind of authentication, but it makes most sense if you are using it in combination with authentication out of the unix password file.

A user is considered to be in a group if either (1) the group is the user's primary group identified by it's gid number in /etc/passwd, or (2) the group is listed in /etc/group and the user id is listed as a member of that group.

By default, mod_authz_unixgroup is authoritative. If you want to use more than one group checker, like mod_authz_unixgroup together with mod_authz_groupfile or mod_authz_dbm, then you'll want to make them non- authoritative, so that if one fails, the other will be tried. You can make mod_authz_unixgroup non-authoritative by saying:

AuthzUnixgroupAuthoritative off

Use with mod_authz_owner:

You can use mod_authz_unixgroup together with mod_authz_owner to do something like:

AuthzUnixgroup on
Require file-group

This would allow access to the page only if the user was a member of whichever unix group owns the file.

You may have to install mod_authz_owner before this will work. Though it is part of the standard Apache distribution, it is not usually installed by default.

Note that when access is denied, either because the file does not exist or because the user is not in the group that owns the file, then the normal response will be for the browser to flush it's cached login and password for the authentication realm, and give the user a new login prompt. The user will have to re-login to access other files in the realm that they do have access to. This may be clumsy in some applications, where it would be much nicer to display a "permission denied" error message and not flush the user's credentials. This can be achieved by telling mod_authz_unixgroup to return a 403 error when authentication fails instead of the normal 401 error:

AuthzUnixgroupError 403

You may want to customize the 403 error page if you do this.