Apache has its own built-in authentication system(s) for providing access control to a site that it's hosting. You've probably encountered this before using "basic" authentication backed by a flatfile created and edited using the htpasswd command.
If you do this using the common guides on the Internet (for example, this guide from Apache itself), then when you go to your site, you'll be presented with your browser's built-in basic-authentication dialog box asking for a username and password. If you provide valid credentials, then you'll be moved on through to the main site, and if you don't, then it'll dump you to a plain "401 Unauthorized" page.
This works fine, but it has three main drawbacks:
- Password managers (such as LastPass) can't detect this dialog box and autofill it, which is very annoying.
- On some mobile browsers, the dialog gets in the way of normal operations. Even if you have multiple tabs open, whatever tab is trying to get you to log in will get in the way and force you to deal with it.
- If you're using Windows authentication, the browser might detect the 401 error and attempt to sign you in using your domain credentials. If the server has a different set of credentials, then it'll mean that you can't actually log in due to Windows trying to auto log in.
(And the built-in popup is really ugly, and it submits the password in plaintext, etc., etc.)
Apache "Form" Authentication
To solve this problem, Apache has a type of authentication called "form" that adds an extra step involving an HTML form (that's fully customizable).
The workflow is as follows:
- Create a login HTML page (you'll have to provide the page).
- Register a handler for that page to POST to (Apache already has the handler).
- Update any "Directory" or "Location" blocks in your Apache config to use the "form" authentication type instead of "basic".
You'll also need these modules installed and enabled:
- mod_auth_form
- mod_request
- mod_session
- mod_session_cookie
On Ubuntu, I believe that these were all installed out of the box but needed to be enabled separately. On Red Hat, I had to install the mod_session package, but everything was otherwise already enabled.
Example
If you want to try out "form" authentication, I recommend that you get everything working with "basic" authentication first. This is especially true if you have multiple directories that need to be configured separately.
For this example, I'm going to use our Nagios server.
There were two directories that needed to be protected: "/usr/local/nagios/sbin" and "/usr/local/nagios/share". This setup is generally described by this document (although it covers "digest" authentication instead of "basic").
For both directories that already had "AuthType" set up, the changes are simple:
- Change AuthType Basic to AuthType Form.
- Change AuthBasicProvider to AuthFormProvider.
- Add the login redirect: AuthFormLoginRequiredLocation "/login.html"
- Enable sessions: Session On
- Set a cookie name: SessionCookieName session path=/
I decided to put my login page at "/login.html" because that makes sense, but you could put it anywhere (and even host it on a different server if you specify a full URL instead of just a path).
That page should contain a "form" with two "input" elements: "httpd_username" and "httpd_password". The form "action" should be set to "/do-login.html" (or whatever handler you want to register with Apache).
At its simplest, "login.html" looks like this:
<form method="POST" action="/do-login.html">
Username: <input type="text" name="httpd_username" value="" />
Password: <input type="password" name="httpd_password" value="" />
<input type="submit" name="login" value="Login" />
</form>
You'll probably want an "html" tag, a title and body and such, maybe some CSS, but this'll get the job done.
The last step is to register the thing that'll actually process the form data: "/do-login.html"
In your Apache config, add a "location" for it:
<Location "/do-login.html">
SetHandler form-login-handler
AuthType form
AuthName "Nagios Access"
AuthFormProvider file
AuthUserFile /path/to/your/htpasswd.users
AuthFormLoginRequiredLocation "/login.html"
AuthFormLoginSuccessLocation "/nagios/"
Session On
SessionCookieName session path=/
</Location>
The key thing here is SetHandler form-login-handler. This tells Apache to use its built-in form handler to take the values from httpd_username and httpd_password and compare them against your authentication provider(s) (in this example, it's just a flatfile, but you could use LDAP, etc.).
The other two options handle the last bit of navigation. AuthFormLoginRequiredLocation sends you back to the login page if the username/password combination didn't work (you could potentially have another page here with an error message pre-written). AuthFormLoginSuccessLocation sends you to the place where you want the user to go after login (I'm sending the user to the main Nagios page, but you could send them anywhere).
Notes
Other Authentication Providers
I've just covered the "file" authentication provider here. If you use "ldap" and/or any others, then that config will need to be copied to every single place where you have "form" authentication set up, just like you would if you were only using the "file" provider.
I found this to be really annoying, since I had two directories to protect plus the form handler, so that brings over another 4 lines or so to each config section, but what matters is that it works.
