Previous Entry Share Next Entry
Important problem-solving tip when setting-up Apache to use "mod_auth_external" with "pwauth"
Universal #2

The Problem

When setting-up mod_auth_external with pwauth, when it comes time to test your setup you may get to a point where you're staring at the following message in the logs:
Invalid AuthExternal keyword (pwauth)

If so, you're receiving this message for one of two reasons; either:

  1. You forgot to use the "AddExternalAuth" and "SetExternalAuthMethod" directives to define the "pwauth" external authenticator somewhere in the Apache logs that the server will actually read; OR

  2. You defined the "pwauth" external authenticator with the "AddExternalAuth" and "SetExternalAuthMethod" directives, but those definitions are in the global scope of the httpd.conf (or file it includes), rather than inside the <VirtualHost> section from which you are trying to use it.

Case 1 is the trivial case of just forgetting a step as part of installation. Step 2, on the other hand, is counter-intuitive behavior on the part of "mod_auth_external" and is very easy to do by accident.

Consider the following /etc/apache2/modules.d/10_mod_authnz_external.conf file taken from Gentoo Linux:
LoadModule authnz_external_module modules/

# provided by net-www/pwauth
AddExternalAuth pwauth /usr/sbin/pwauth
SetExternalAuthMethod pwauth pipe

# For external group check (provided by net-www/pwauth)
AddExternalGroup unixgroup /usr/sbin/unixgroup
SetExternalGroupMethod unixgroup environment

At least in the Gentoo distro, Apache includes this file in httpd.conf, as follows:
Include /etc/apache2/modules.d/*.conf

This essentially means that the "pwauth" external authenticator and "unixgroup" external group authenticator are defined in the "global" scope of the configuration file, rather than being associated with a particular virtual host. One would naturally assume, then, that these two would be available from within any <VirtualHost> section, but that turns out not to be the case.

For example, consider the situation below:
<VirtualHost *:80>
    <Directory /var/www/vhosts/>
        Order Deny,Allow

        AuthType Basic
        AuthName "Red Bottle Design - Developers"
        AuthBasicProvider external
        AuthExternal pwauth

        GroupExternal unixgroup
        Require group developers

In this scenario, the bolded directives above would be the cause of the "Invalid AuthExternal keyword" and "Invalid GroupExternal keyword" errors.

The Solution

There are two solutions to this conundrum; either:

  1. Move the authentication directives (AuthType, AuthName, AuthBasicProvider, etc). into an .htaccess file in the top-level folder of the website. Oddly enough, the .htaccess file does have access to these authentication providers defined in global scope; OR

  2. Follow the recommendation from the "Communication" section of the article in the Gentoo Wiki about setting this up and put authenticator definitions in a separate auth.include file that you can include from multiple virtual hosts.

I went with option 2, since I don't like the idea of security on some sites going away as easily as just losing an .htaccess file. Personally, though, I feel this is some counter-intuitive behavior that should be addressed, because global definitions should still be available in <VirtualHost> sections.

  • 1
Thank you very much, I was defining pwauth in a global scope and using it in a virtualhost. You saved my evening.

Very good post! We will be linking to this great post on our
website. Keep up the good writing.

Thanks. I too was wondering why it didn't work. I understand now.

It was not easy to figure out the problem, thanks for your help !


It is a perfect solution. Many Thanks

Greetin from México

  • 1

Log in